Agent mode: Create a response

POST /api/2.0/genie/agents/{agent_id}/responses

Sends a question to a Genie agent and streams the response over Server-Sent Events (SSE). Omit conversation_id to start a conversation, or provide it to continue an existing agent-mode conversation. Disconnecting the stream does not cancel the response; use the cancel response endpoint to stop it.

API scopes: genie

Path parameters

agent_idstringRequiredpath

The ID of the Genie agent.

Request body

inputarray of objectRequired

Exactly one message item with role: "user" containing the question.

Show child attributesHide child attributes

typestringRequired

Item type. Use message.

Values:

• message

rolestringRequired

Message role. Use user.

Values:

• user

contentarray of objectRequired

Message content. Each item is {"type": "input_text", "text": "..."}.

conversation_idstring

Existing conversation to continue. Omit to start a new one.

Default: null

execution_modestringBeta

The agent mode option for a new conversation. Flash prioritizes response speed on simple tasks. Set FLASH to use Flash, which must be available for the workspace. Omit the field or set STANDARD to use standard agent mode.

The option is set when the conversation is created and applies to every turn. On a follow-up, omit the field or repeat the conversation's option; a different value fails with BAD_REQUEST. To switch options, start a new conversation.

Default: null

Values:

• STANDARD
• FLASH

enable_vizboolean

Set to true to request visualization generation when visualizations are available and appropriate for the response.

Default: false

Response events

Every event contains a monotonically increasing sequence_number. The stream ends with response.completed on success or response.failed on failure. The server-side timeout is 30 minutes.

response.createdevent

Sent once when the stream opens. data.response is a Response with status: "in_progress" and empty output.

response.output_item.addedevent

A new output item appears and might still be in progress. data.item is an output item.

response.output_item.updatedevent

An existing item's content changed. It has the same shape as response.output_item.added.

response.output_item.doneevent

An item reached its final state. It has the same shape as response.output_item.added.

response.completedevent

Terminal success. data.response is the final Response with all output items.

response.failedevent

Terminal failure. data.response.status is "failed" and includes an error object.

Response

The response uses the text/event-stream content type.

objectstring

Always "response".

Values:

• response

idstring

Unique response ID.

modelstring

Always "genie-agent".

Values:

• genie-agent

statusstring

The response status.

Values:

• in_progress
• completed
• failed

outputarray of object

Output items produced by this response. Each item is polymorphic on type.

Show child attributesHide child attributes

reasoningobject

The agent's reasoning. Contains reasoning_text content items and a status.

function_callobject

An SQL query the agent runs. Contains call_id, the name "execute_sql", and arguments encoded as a JSON string. It is paired with function_call_output by call_id.

function_call_outputobject

The query result. Its ID is always {call_id}_output; when completed, output contains the query title followed by a Markdown table.

messageobject

A user question, assistant report, or system error. Assistant content contains output_text chunks; table chunks include metadata for columns, preview rows, total row count, status, and SQL.

conversation_idstring

The conversation this response belongs to. Reuse it to list items or send follow-up questions.

created_atinteger

Unix epoch time in seconds.

errorobject

Present when status is "failed".

Errors

HTTP status	Error code	Description
400	INVALID_PARAMETER_VALUE	A path parameter is missing, or input is not exactly one message item with role: "user".
400	BAD_REQUEST	execution_mode is not STANDARD or FLASH, or a follow-up sets a different execution_mode than the conversation was created with.
404	FEATURE_DISABLED	The workspace is not enrolled or the preview toggle is off, or execution_mode is FLASH and Flash is not available for the workspace.
403	PERMISSION_DENIED	The caller lacks CAN QUERY on the Genie agent.
404	NOT_FOUND	The Genie agent or conversation does not exist.
409	RESOURCE_CONFLICT	A response is already being generated for this conversation.
429	RATE_LIMIT_EXCEEDED	The request was rate limited due to detected non-organic usage patterns or resource limitations.
500	INTERNAL_ERROR	An unexpected server error occurred.

View as Markdown

Request

{
  "enable_viz": true,
  "execution_mode": "FLASH",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What were our top 10 customers by revenue last quarter?"
        }
      ]
    }
  ]
}

Response

event: response.created
data:
{
  "type": "response.created",
  "sequence_number": 0,
  "response": {
    "object": "response",
    "id": "01f14fe4e34b...",
    "model": "genie-agent",
    "status": "in_progress",
    "output": [],
    "conversation_id": "01f14fe4e338..."
  }
}

event: response.output_item.added
data:
{
  "type": "response.output_item.added",
  "output_index": 0,
  "sequence_number": 1,
  "item": {
    "type": "reasoning",
    "id": "01f14fe4f248...",
    "status": "in_progress",
    "content": [
      {
        "type": "reasoning_text",
        "text": "I need to find revenue data..."
      }
    ],
    "summary": []
  }
}

event: response.completed
data:
{
  "type": "response.completed",
  "sequence_number": 42,
  "response": {
    "object": "response",
    "id": "01f14fe4e34b...",
    "model": "genie-agent",
    "status": "completed",
    "output": [ ... ],
    "conversation_id": "01f14fe4e338...",
    "created_at": 1748383200
  }
}