Create an agent mode 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).

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

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".
404	FEATURE_DISABLED	The workspace is not enrolled or the preview toggle is off.
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 per-workspace rate limit of five requests per minute was exceeded.
500	INTERNAL_ERROR	An unexpected server error occurred.

View as Markdown

Request

{
  "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
  }
}