Run a Sigma agent

POST

/v2/workbooks/:workbookId/agents/:agentId

POST

/v2/workbooks/:workbookId/agents/:agentId

curl -X POST https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "messages": [
    {
      "content": "Summarize this month'\''s sales trends.",
      "role": "user"
    }
  ]
}'

{
  "object": "agent.run",
  "runId": "018f5a6e-9c2b-7d41-8e3a-2b6f9c1d4a70",
  "createdAt": 1716312245,
  "completedAt": 1716312248,
  "model": "gpt-5.1-2025-11-13",
  "status": "completed",
  "incompleteDetails": null,
  "output": [
    {
      "content": "You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.",
      "role": "user"
    },
    {
      "content": "Sales grew 8% month-over-month, led by the Northeast region.",
      "role": "assistant"
    }
  ],
  "usage": {
    "turns": 2,
    "durationMs": 3210,
    "inputTokens": 512,
    "outputTokens": 24,
    "totalTokens": 536
  },
  "workbookVersion": 14
}

Run a Sigma agent and return its reply.

The API is stateless. Include the full conversation in messages on every call. To continue a conversation, append the response output to your messages and send them on the next call. The agent runs with your access against the workbook’s latest published version unless you pass versionTagName. For a guide to calling Sigma agents from the API, see Call Sigma agents with the API.

Usage notes

Retrieve the workbookId by calling the /v2/workbooks endpoint.
Retrieve the agentId by calling the /v2/workbooks/{workbookId}/agents endpoint.
Retrieve the versionTagName by calling the /v2/tags endpoint and using the name in the response. Omit to run against the latest published version.
If the workbookVersion changes between turns, the workbook was published mid-conversation.

Usage scenarios

Evaluate agent responses: Include the response runId in support requests, and use it to correlate runs with your logs.

Run a Sigma agent and return its reply. The API is stateless. Include the full conversation in `messages` on every call. To continue a conversation, append the response `output` to your `messages` and send them on the next call. The agent runs with your access against the workbook's latest published version unless you pass `versionTagName`. For a guide to calling Sigma agents from the API, see [Call Sigma agents with the API](https://help.sigmacomputing.com/docs/call-agents-with-the-api). ### Usage notes - Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint. - Retrieve the **agentId** by calling the [/v2/workbooks/{workbookId}/agents](https://help.sigmacomputing.com/reference/list-agents-in-workbook) endpoint. - Retrieve the **versionTagName** by calling the [/v2/tags](https://help.sigmacomputing.com/reference/list-version-tag) endpoint and using the `name` in the response. Omit to run against the latest published version. - If the `workbookVersion` changes between turns, the workbook was published mid-conversation. ### Usage scenarios - **Evaluate agent responses**: Include the response `runId` in support requests, and use it to correlate runs with your logs.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Path parameters

workbookIdstringRequired

Unique identifier of the workbook that contains the agent.

agentIdstringRequired

Unique identifier of the Sigma agent to run.

Request

The request body.

messageslist of objectsRequired

Full conversation contents.

streambooleanOptional

When true, the response is a stream of events instead of a single JSON body. Defaults to false.

sigma:versionTagNamestringOptional

Name of the version tag whose workbook version to run the agent against. Omit to run against the latest published version.

responseFormatobjectOptional

maxTurnsdoubleOptional

Maximum tool-calling steps per turn before the agent stops running. Default 50, max 100.

maxOutputTokensdoubleOptional

Maximum total output tokens the agent can generate. When omitted, no limit is applied.

metadatamap from strings to strings or doubles or booleansOptional

Caller-defined key/value metadata logged to the ai_usage table in your warehouse.

Response

The response body.

objectenum

Object type, always agent.run.

Allowed values:

runIdstring

Unique identifier for the agent run.

createdAtdouble

Unix timestamp (in seconds) of when the run began.

completedAtdouble or null

Unix timestamp (in seconds) when the run completed.

modelstring

Identifier of the model that served the run.

statusenum

Status of the run.

Allowed values:

incompleteDetailsobject or null

Details about why the run is incomplete, or null when the run completed normally.

outputlist of objects

The agent's reply turn, containing the answer text and any tool calls or tool results.

usageobject

outputParsedobjectOptional

The agent’s answer parsed into the structure requested in responseFormat. Present only when a responseFormat was specified and the output satisfied it.

outputErrorstringOptional

Present when a responseFormat was requested but the structured output could not be produced or failed schema validation.

workbookVersiondoubleOptional

Workbook version used to run the agent turn.