Response

View as Markdown

Create and stream a Genie One response, or retrieve it later.

Create a responsePOST /api/2.0/genie/one/responsesGet a responseGET /api/2.0/genie/one/conversations/{conversation_id}/responses/{response_id}

Response object

A stored Genie One response.

idstringBetaOutput only

The opaque response identifier.

objectstringBetaOutput only

Always response.

modelstringBetaOutput only

The server-managed model profile, genie-one.

statusstringBetaOutput only

One of in_progress, completed, failed, or incomplete.

outputarray of objectBetaOutput only

The public assistant messages produced by this response, in output order.

Show child attributesHide child attributes

typestringBetaOutput only

The item discriminator, message.

idstringBetaOutput only

The opaque item identifier. Clients must not parse or derive identifiers from it.

rolestringBetaOutput only

Always assistant. To retrieve user messages, list the conversation items.

contentarray of objectBetaOutput only

The ordered text parts of the message.

Show child attributesHide child attributes

typestringBetaOutput only

Always output_text.

textstringBetaOutput only

The text of this content part. Output text may contain Markdown, including result tables.

annotationsarray of objectBetaOutput only

Public source references used by the assistant text. The array can be empty.

Show child attributesHide child attributes

typestringBetaOutput only

The citation discriminator, asset.

titlestringBetaOutput only

The customer-visible source title.

asset_typestringBetaOutput only

The kind of cited source, such as TABLE, NOTEBOOK, or WEB.

identifierstringBetaOutput only

The public asset identifier, volume path, or source web URL.

indexint32BetaOutput only

The one-based citation number. It is neither a character offset nor an index into annotations. Numbers remain stable if unsupported citations are omitted.

statusstringBetaOutput only

The lifecycle status of this message, when available.

phasestringBetaOutput only

The assistant message phase: commentary or final_answer.

create_timestringBetaOutput only

The message creation time as an RFC 3339 timestamp, when available.

complete_timestringBetaOutput only

The message completion time as an RFC 3339 timestamp, when available.

conversation_idstringBetaOutput only

The conversation that contains the response.

create_timestringBetaOutput only

The response creation time as an RFC 3339 timestamp, when available.

errorobjectBetaOutput only

Sanitized failure information on a failed response, when available.

Show child attributesHide child attributes

typestringBetaOutput only

The stable public error category.

messagestringBetaOutput only

A sanitized customer-facing description.

codestringBetaOutput only

The stable Genie One error code, such as internal_error, when available.

retryablebooleanBetaOutput only

Whether retrying the failed response may succeed.

previous_response_idstringBetaOutput only

The preceding response in the conversation, when this response has a parent.

View as Markdown

The Response object

{
  "id": "9f7c84c6d3af4ae8ac5cc43590a15366",
  "object": "response",
  "model": "genie-one",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "2b6aa43956be4fe89ff68ccb565a214d",
      "role": "assistant",
      "status": "completed",
      "phase": "final_answer",
      "create_time": "2026-10-19T10:01:01Z",
      "complete_time": "2026-10-19T10:01:06Z",
      "content": [
        {
          "type": "output_text",
          "text": "Revenue increased 12% last quarter.",
          "annotations": []
        }
      ]
    }
  ],
  "conversation_id": "6a34b9a50cb4435da7c463130c9d42c1",
  "create_time": "2026-10-19T10:01:00Z"
}

Create a response Beta

POST /api/2.0/genie/one/responses

Sends a question to Genie One and streams the response over Server-Sent Events (SSE). Omit conversation_id to start a conversation, or provide it to continue an existing Genie One conversation. The workspace must have Genie One API access enabled.

Save the response.id and response.conversation_id from response.created. Use them to get the response if the stream disconnects. Disconnecting does not cancel an accepted response. Repeating a POST can create another response.

API scopes: genie

Request body

Send only the fields listed below. Unknown request fields return INVALID_PARAMETER_VALUE.

inputstring or array of objectRequired

The question. Send a nonblank string, or an array containing exactly one user message. In the array form, set role to "user"; the message's type can be omitted or set to "message".

The message's content can be a nonblank string or an array of one or more {"type": "input_text", "text": "..."} parts. Each text part must be nonblank. The combined text must not exceed 25,000 UTF-8 bytes. Other message roles and content types are not supported.

conversation_idstring

An existing Genie One conversation to continue. Omit to create a conversation. The caller must be allowed to add responses to it. The ID can contain ASCII letters, digits, hyphens, and underscores, up to 128 bytes.

warehouse_idstring

The SQL warehouse to use if Genie One runs a query. If omitted, Genie One resolves the warehouse.

user_timezonestring

An IANA time zone, such as America/Los_Angeles. The value must not exceed 255 UTF-8 bytes.

enable_vizboolean

Omit this field or set it to false. Requests with true are rejected; visualization payloads are not available through this API.

Default: false

Response events

A successful request returns text/event-stream. Each JSON event has a type matching the SSE event name and a sequence_number that increases from zero. Output item events also have a zero-based output_index. A terminal response event is followed by data: [DONE]. Commentary can stream before completion. Final answer item events can arrive just before the terminal response event.

response.createdevent

The response has been accepted. data.response.status is "in_progress" and data.response.output is empty. Save its response and conversation IDs.

response.output_item.addedevent

A public assistant message is added. data.item is the message and data.output_index is its position in the response output.

response.output_item.updatedevent

A subsequent snapshot of an existing public assistant message. The item has the same shape as response.output_item.added. Replace the previous item at its output_index rather than appending its text.

response.output_item.doneevent

A public assistant message reaches its final state. The item appears in the terminal response's output array.

response.completedevent

Terminal success. data.response.status is "completed" and its output contains the public assistant messages.

response.failedevent

Terminal failure after the response was accepted. data.response.status is "failed". A sanitized error object is included when failure details are available.

response.incompleteevent

The response stopped without completing. data.response.status is "incomplete".

Response

The response.created and terminal events carry the Response object. Its output contains public assistant messages only. Internal reasoning, tool calls, tool results, and visualization payloads are not output items. Answer text can include Markdown tables.

Errors

Requests rejected before streaming return a JSON error with an HTTP status. After a response is accepted, execution failures appear in the SSE stream as response.failed, even though the HTTP status is 200.

HTTP status	Error code	Description
400	INVALID_PARAMETER_VALUE	The request body is malformed or uses an unknown field, unsupported input, or unsupported option.
401	UNAUTHENTICATED	An authenticated identity is required.
403	PERMISSION_DENIED	The caller cannot add a response to the conversation.
404	NOT_FOUND	The API is not enabled for the workspace, or the conversation or specified warehouse is unavailable.
409	ALREADY_EXISTS	Another response is active in the conversation. Retry after it finishes.
429	RESOURCE_EXHAUSTED	The request was rate limited.
500	INTERNAL_ERROR	An unexpected server error occurred.

View as Markdown

Request

{
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "How did revenue change last quarter?"
        }
      ]
    }
  ]
}

Response

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"object":"response","id":"9f7c84c6d3af4ae8ac5cc43590a15366","model":"genie-one","status":"in_progress","output":[],"conversation_id":"6a34b9a50cb4435da7c463130c9d42c1","create_time":"2026-10-19T10:01:00Z"}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":1,"output_index":0,"item":{"type":"message","id":"2b6aa43956be4fe89ff68ccb565a214d","role":"assistant","status":"in_progress","phase":"final_answer","create_time":"2026-10-19T10:01:01Z","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":2,"output_index":0,"item":{"type":"message","id":"2b6aa43956be4fe89ff68ccb565a214d","role":"assistant","status":"completed","phase":"final_answer","create_time":"2026-10-19T10:01:01Z","complete_time":"2026-10-19T10:01:06Z","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","sequence_number":3,"response":{"object":"response","id":"9f7c84c6d3af4ae8ac5cc43590a15366","model":"genie-one","status":"completed","output":[{"type":"message","id":"2b6aa43956be4fe89ff68ccb565a214d","role":"assistant","status":"completed","phase":"final_answer","create_time":"2026-10-19T10:01:01Z","complete_time":"2026-10-19T10:01:06Z","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}],"conversation_id":"6a34b9a50cb4435da7c463130c9d42c1","create_time":"2026-10-19T10:01:00Z"}}

data: [DONE]

Get a response Beta

GET /api/2.0/genie/one/conversations/{conversation_id}/responses/{response_id}

Gets the current or terminal response without starting another execution. Use the response and conversation IDs from response.created to recover after a CreateResponse stream disconnects. Poll while the status is in_progress.

Parameters

conversation_idstringRequiredpath

The conversation that contains the response.

response_idstringRequiredpath

The response to retrieve.

Response

Returns the Response object. The response create_time, when available, is an RFC 3339 timestamp. Output contains public assistant messages only. Failed responses can include a sanitized error.

View as Markdown

Response

{
  "id": "9f7c84c6d3af4ae8ac5cc43590a15366",
  "object": "response",
  "model": "genie-one",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "2b6aa43956be4fe89ff68ccb565a214d",
      "role": "assistant",
      "status": "completed",
      "phase": "final_answer",
      "create_time": "2026-10-19T10:01:01Z",
      "complete_time": "2026-10-19T10:01:06Z",
      "content": [
        {
          "type": "output_text",
          "text": "Revenue increased 12% last quarter.",
          "annotations": []
        }
      ]
    }
  ],
  "conversation_id": "6a34b9a50cb4435da7c463130c9d42c1",
  "create_time": "2026-10-19T10:01:00Z"
}