# Create an agent mode response

:::::::::operation{method="POST" path="/api/2.0/genie/agents/{agent_id}/responses" md="/genie/v1/agent-mode-create-response.md"}

Sends a question to a Genie agent and streams the response over Server-Sent Events (SSE).

**API scopes:** `genie`

## Path parameters

::::::::attribute{name="agent_id" type="string" required loc="path"}
The ID of the Genie agent.
::::::::

## Request body

::::::::attribute{name="input" type="array of object" required}
Exactly one `message` item with `role: "user"` containing the question.

:::::::attribute{name="type" type="string" required enum="message"}
Item type. Use `message`.
:::::::

:::::::attribute{name="role" type="string" required enum="user"}
Message role. Use `user`.
:::::::

:::::::attribute{name="content" type="array of object" required}
Message content. Each item is `{"type": "input_text", "text": "..."}`.
:::::::
::::::::

::::::::attribute{name="conversation_id" type="string" default="null"}
Existing conversation to continue. Omit to start a new one.
::::::::

## 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.

::::::::attribute{name="response.created" type="event"}
Sent once when the stream opens. `data.response` is a `Response` with
`status: "in_progress"` and empty `output`.
::::::::

::::::::attribute{name="response.output_item.added" type="event"}
A new output item appears and might still be in progress. `data.item` is an
output item.
::::::::

::::::::attribute{name="response.output_item.updated" type="event"}
An existing item's content changed. It has the same shape as
`response.output_item.added`.
::::::::

::::::::attribute{name="response.output_item.done" type="event"}
An item reached its final state. It has the same shape as
`response.output_item.added`.
::::::::

::::::::attribute{name="response.completed" type="event"}
Terminal success. `data.response` is the final `Response` with all output
items.
::::::::

::::::::attribute{name="response.failed" type="event"}
Terminal failure. `data.response.status` is `"failed"` and includes an `error`
object.
::::::::

## Response

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

::::::::attribute{name="object" type="string" enum="response"}
Always `"response"`.
::::::::

::::::::attribute{name="id" type="string"}
Unique response ID.
::::::::

::::::::attribute{name="model" type="string" enum="genie-agent"}
Always `"genie-agent"`.
::::::::

::::::::attribute{name="status" type="string" enum="in_progress,completed,failed"}
The response status.
::::::::

::::::::attribute{name="output" type="array of object"}
Output items produced by this response. Each item is polymorphic on `type`.

:::::::attribute{name="reasoning" type="object"}
The agent's reasoning. Contains `reasoning_text` content items and a status.
:::::::

:::::::attribute{name="function_call" type="object"}
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`.
:::::::

:::::::attribute{name="function_call_output" type="object"}
The query result. Its ID is always `{call_id}_output`; when completed, `output`
contains the query title followed by a Markdown table.
:::::::

:::::::attribute{name="message" type="object"}
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.
:::::::
::::::::

::::::::attribute{name="conversation_id" type="string"}
The conversation this response belongs to. Reuse it to list items or send
follow-up questions.
::::::::

::::::::attribute{name="created_at" type="integer"}
Unix epoch time in seconds.
::::::::

::::::::attribute{name="error" type="object"}
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. |

:::sample{label="Request" language="json"}
```json
{
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What were our top 10 customers by revenue last quarter?"
        }
      ]
    }
  ]
}
```
:::

:::sample{label="Response" language="text"}
```text
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
  }
}
```
:::

:::::::::