Conversations and history

Use the quickstart client. Replace uppercase IDs with your resource IDs.

Conversations

Method	Purpose
`conversations.create({ title }?, options?)`	Creates an idle conversation without running the agent.
`conversations.list(options?)`	Lists accessible conversations.
`conversations.retrieve(id, options?)`	Reads the title and active response IDs.
`conversations.update(id, { title }, options?)`	Renames the conversation.
`conversations.delete(id, options?)`	Starts or completes deletion.
`conversations.items.list(id, options?)`	Reads input, answer, and output history.
`conversations.generationSummary(id, options?)`	Reads generation cost information.

import { agent } from "./client.ts";
const conversation =
  await agent.conversations.create({
    title: "Product campaign",
  });
const response = await agent.run({
  conversation: conversation.id,
  input:
    "Suggest a visual direction. Do not generate media.",
});
console.log(conversation.id, response.id);

Conversation titles have a maximum of 120 characters. A rename requires a nonempty title after trimming. conversations.retrieve returns id, title, and active_response_ids.

Paginate history

Conversation and history list methods return { data, next_cursor }. Page options accept cursor and a limit from 1 to 100.

import { agent } from "./client.ts";

let cursor: string | undefined;
do {
  const page = await agent.conversations.items.list(
    "CONVERSATION_ID",
    {
      cursor,
    },
  );
  console.log(page.data);
  cursor = page.next_cursor ?? undefined;
} while (cursor);

History items contain id, response_id, and sequence_number. An item’s type determines its payload. input contains a request input, answer contains an input request ID and answer, and output contains an output item. The response ID can be null. See AgentConversationItem. History pagination returns 409 if the underlying snapshot changes. Discard the accumulated pages and restart from the first page.

Fork a conversation

import { agent } from "./client.ts";

const fork = await agent.conversations.fork(
  "CONVERSATION_ID",
  {
    atMessageId: "MESSAGE_ID",
  },
);
console.log(fork.id);

The fork copies settled history through the selected message’s completed turn. Omit atMessageId to copy the available settled history. Active turns are excluded. The optional createProject field controls project creation. Project placement completes asynchronously.

import { agent } from "./client.ts";

const share =
  await agent.conversations.sharing.update(
    "CONVERSATION_ID",
    {
      emails: ["reviewer@example.com"],
    },
  );
console.log(
  `https://fal.ai/chat/share/${share.id}`,
);

This replaces the policy. Empty recipient lists allow anyone with the link to access the conversation. Use allowedAccountIds for account access or scopedAccountId with scopedEmails for recipients within one account. The optional expiresAt field accepts an ISO 8601 timestamp. Omitting it or passing null removes expiration. Read the current policy with conversations.sharing.retrieve(id) before replacing it. The result is null when no policy exists.

Delete a conversation

Deletion can return { deleted: false } while running work stops. Repeat the deletion request to complete cleanup.

Recover uncertain writes

Conversation creation is sent once. Rename and deletion can use transport retries. Read the resource after a lost acknowledgement before deciding whether to repeat the write. Request options support signal and timeoutMs.

Setting Up

Model APIs

Serverless

Compute

Organizations

fal Agent

fal Assets

Conversations and history

Conversations

Paginate history

Fork a conversation

Delete a conversation

Recover uncertain writes

​Conversations

​Paginate history

​Fork a conversation

​Share a conversation

​Delete a conversation

​Recover uncertain writes

​Related resources

Conversations

Paginate history

Fork a conversation

Share a conversation

Delete a conversation

Recover uncertain writes

Related resources