> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Call Sigma agents with the API (Beta)

> Use the Sigma agent API to run a Sigma agent from your own application, choose between streaming and non-streaming responses, and continue conversations across requests.

* This documentation describes one or more public beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page. This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see [Beta features](/docs/sigma-product-releases#beta-features).
* Sigma agents are a premium feature. While Sigma agents are in beta, anyone in your organization with access to a workbook can use agents. To maintain access to Sigma agents after the beta, contact your Sigma Account Executive.
* The use of AI features is subject to the following [disclaimer](/docs/notice-for-enabling-ai-enabled-features-in-sigma).

You can run a [Sigma agent](/docs/sigma-agents) programmatically with the Sigma REST API and use the reply in your own application, instead of interacting with the agent through a [chat element](/docs/chat-with-agent) or action in a workbook.

For example, you can use the API to embed a Sigma agent in a custom chat interface in your own application or call an agent from a script or an automated pipeline.

#### From a custom application

Call the endpoint from your application's backend, using the non-streaming response for simple integrations or the streaming response to power a live chat experience.

#### From a script or automation

Call the endpoint from a scheduled job or pipeline step, using the non-streaming response and, optionally, `responseFormat` to get output you can parse and act on programmatically.

The API runs the agent with the calling user's permissions and row-level security, using the same instructions, data sources, and tools configured for the agent in the workbook.

## User requirements

To call an agent using the API, you must have the following:

* Client credentials with the REST API scope
* The client credentials must be assigned to a user with at least **Can view** access to the workbook containing the agent that you want to run.

## Limitations

* You cannot interact with a warehouse agent using this API endpoint. Instead, use the API endpoints associated with your data platform.
* Some action tools do not run when called programmatically. For a list of action tools that run when called by an agent run programmatically, see [About automated action sequences](/docs/configure-action-sequences-to-run-automatically#about-automated-action-sequences).
* Only one system message can be specified per conversation.

## What you can do with the agent API

The agent API is a stateless, chat-completion-style endpoint. With it, you can do any of the following:

* Send a full conversation and get the agent's next reply, including any text, tool calls, and tool results.
* Continue a multi-turn conversation by replaying the previous output as part of the next request's messages.
* Retrieve the agent response as a structured JSON schema, instead of free-form text.
* Limit a run with a maximum number of tool-calling steps (`maxTurns`) or a maximum number of output tokens (`maxOutputTokens`).
* Run the agent against a tagged version of the workbook, instead of the latest published version.
* Attach caller-defined metadata to a run, which is logged to the `ai_usage` table (if [configured](/docs/configure-a-usage-dashboard-for-assistant)) in your data platform for tracking and auditing.
* Stream the agent's reply as a sequence of events instead of waiting for the full turn to complete.

### Decide whether to retrieve a streaming response

By default, the agent API returns a single JSON response after the agent finishes its turn. Set `stream` to `true` in the request to instead receive a sequence of events as the agent works.

Decide which response type fits your use case by reviewing the following table:

|                     | Non-streaming (default)                                                                                          | Streaming (`stream: true`)                                                                                |
| :------------------ | :--------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |
| Use case            | Scripts, automation, backend jobs                                                                                | Interactive chat interface                                                                                |
| Client requirements | HTTP client that can parse a JSON response                                                                       | Client that can read an event stream and reconstruct incremental text and tool call arguments.            |
| Latency             | Appears longer because you wait for the entire run, including tool calls, to complete before you see any output. | Appears shorter because you see status updates and partial text as soon as they're produced by the agent. |

## Get started calling an agent with the API

To get started calling an agent with the API:

1. Identify the agents that you have access to. You can call the [List agents](/reference/list-workbook-agents) endpoint to retrieve the list of all agents that you can access in your Sigma organization, including the `workbookId` and `agentId` of each agent.
2. Decide whether to modify the default request with optional details, such as:

   * Send your user prompt as a message with `"role": "user"` in the `messages` list.
   * Determine whether your use case needs a streaming or non-streaming response.
   * Determine whether you want to receive a response as text or structured JSON.
   * Specify arbitrary metadata to be logged to the `AI_USAGE` table.
   * Include previous conversation output as context in the `messages` list. See [Continue a conversation](#continue-a-conversation).

## Run an agent

To run an agent, send a `POST` request to the [Run a Sigma agent](/reference/run-agent) endpoint.

* Include the `workbookId` and `agentId` for the agent.
* Specify relevant content in the request.
* If you want to add system-level context to the agent instructions, such as "never tell the user what source you are querying", include that as a `system` message.
* Store the returned `runId` alongside your own logs so you can correlate a run with a support request if needed.

### Request

POST [https://api.sigmacomputing.com/v2/workbooks/\{workbookId}/agents/\{agentId}](https://api.sigmacomputing.com/v2/workbooks/\{workbookId}/agents/\{agentId})

**`Simple prompt`**

```curl Simple prompt
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"
    }
  ]
}'
```

**`Simple prompt`**

```python Simple prompt
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

payload = { "messages": [
        {
            "content": "Summarize this month's sales trends.",
            "role": "user"
        }
    ] }
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Simple prompt`**

```javascript Simple prompt
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId';
const options = {
  method: 'POST',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Summarize this month\'s sales trends.","role":"user"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Simple prompt`**

```go Simple prompt
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Simple prompt`**

```ruby Simple prompt
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

**`Simple prompt`**

```java Simple prompt
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}")
  .asString();
```

**`Simple prompt`**

```php Simple prompt
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId', [
  'body' => '{
  "messages": [
    {
      "content": "Summarize this month\'s sales trends.",
      "role": "user"
    }
  ]
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

**`Simple prompt`**

```csharp Simple prompt
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Simple prompt`**

```swift Simple prompt
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = ["messages": [
    [
      "content": "Summarize this month's sales trends.",
      "role": "user"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

The response includes the agent's reply in `output`, along with usage details about the run, such as the number of turns and tokens consumed.

### Continue a conversation

Chat history is not currently stored for agents, so to continue a conversation with an agent, provide the context about the current conversation when making a request to run the agent.

To continue a conversation, append the previous response's `output` to the `messages` array and send the full history again on the next call:

### Request

POST [https://api.sigmacomputing.com/v2/workbooks/\{workbookId}/agents/\{agentId}](https://api.sigmacomputing.com/v2/workbooks/\{workbookId}/agents/\{agentId})

**`Continue a conversation`**

```curl Continue a conversation
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"
    },
    {
      "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"
    },
    {
      "content": "Which product drove that growth?",
      "role": "user"
    }
  ]
}'
```

**`Continue a conversation`**

```python Continue a conversation
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

payload = { "messages": [
        {
            "content": "Summarize this month's sales trends.",
            "role": "user"
        },
        {
            "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"
        },
        {
            "content": "Which product drove that growth?",
            "role": "user"
        }
    ] }
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Continue a conversation`**

```javascript Continue a conversation
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId';
const options = {
  method: 'POST',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Summarize this month\'s sales trends.","role":"user"},{"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"},{"content":"Which product drove that growth?","role":"user"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Continue a conversation`**

```go Continue a conversation
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"Sales grew 8% month-over-month, led by the Northeast region.\",\n      \"role\": \"assistant\"\n    },\n    {\n      \"content\": \"Which product drove that growth?\",\n      \"role\": \"user\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Continue a conversation`**

```ruby Continue a conversation
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"Sales grew 8% month-over-month, led by the Northeast region.\",\n      \"role\": \"assistant\"\n    },\n    {\n      \"content\": \"Which product drove that growth?\",\n      \"role\": \"user\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

**`Continue a conversation`**

```java Continue a conversation
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"Sales grew 8% month-over-month, led by the Northeast region.\",\n      \"role\": \"assistant\"\n    },\n    {\n      \"content\": \"Which product drove that growth?\",\n      \"role\": \"user\"\n    }\n  ]\n}")
  .asString();
```

**`Continue a conversation`**

```php Continue a conversation
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId', [
  'body' => '{
  "messages": [
    {
      "content": "Summarize this month\'s sales trends.",
      "role": "user"
    },
    {
      "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"
    },
    {
      "content": "Which product drove that growth?",
      "role": "user"
    }
  ]
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

**`Continue a conversation`**

```csharp Continue a conversation
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"You are a sales analytics assistant. Answer questions using the connected sales data, and never reveal the name of the underlying data source.\",\n      \"role\": \"user\"\n    },\n    {\n      \"content\": \"Sales grew 8% month-over-month, led by the Northeast region.\",\n      \"role\": \"assistant\"\n    },\n    {\n      \"content\": \"Which product drove that growth?\",\n      \"role\": \"user\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Continue a conversation`**

```swift Continue a conversation
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = ["messages": [
    [
      "content": "Summarize this month's sales trends.",
      "role": "user"
    ],
    [
      "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"
    ],
    [
      "content": "Which product drove that growth?",
      "role": "user"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Retrieve structured output

If you want to structure the output returned by the agent, you can specify a desired JSON output structure when you make a request:

### Request

POST [https://api.sigmacomputing.com/v2/workbooks/\{workbookId}/agents/\{agentId}](https://api.sigmacomputing.com/v2/workbooks/\{workbookId}/agents/\{agentId})

**`Structured JSON output`**

```curl Structured JSON output
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"
    }
  ],
  "responseFormat": {
    "jsonSchema": {
      "properties": {
        "percentChange": {
          "type": "number"
        },
        "summary": {
          "type": "string"
        }
      },
      "required": [
        "summary",
        "percentChange"
      ],
      "type": "object"
    },
    "type": "json_schema"
  }
}'
```

**`Structured JSON output`**

```python Structured JSON output
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

payload = {
    "messages": [
        {
            "content": "Summarize this month's sales trends.",
            "role": "user"
        }
    ],
    "responseFormat": {
        "jsonSchema": {
            "properties": {
                "percentChange": { "type": "number" },
                "summary": { "type": "string" }
            },
            "required": ["summary", "percentChange"],
            "type": "object"
        },
        "type": "json_schema"
    }
}
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Structured JSON output`**

```javascript Structured JSON output
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId';
const options = {
  method: 'POST',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"messages":[{"content":"Summarize this month\'s sales trends.","role":"user"}],"responseFormat":{"jsonSchema":{"properties":{"percentChange":{"type":"number"},"summary":{"type":"string"}},"required":["summary","percentChange"],"type":"object"},"type":"json_schema"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Structured JSON output`**

```go Structured JSON output
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId"

	payload := strings.NewReader("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"responseFormat\": {\n    \"jsonSchema\": {\n      \"properties\": {\n        \"percentChange\": {\n          \"type\": \"number\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"summary\",\n        \"percentChange\"\n      ],\n      \"type\": \"object\"\n    },\n    \"type\": \"json_schema\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Structured JSON output`**

```ruby Structured JSON output
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"responseFormat\": {\n    \"jsonSchema\": {\n      \"properties\": {\n        \"percentChange\": {\n          \"type\": \"number\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"summary\",\n        \"percentChange\"\n      ],\n      \"type\": \"object\"\n    },\n    \"type\": \"json_schema\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

**`Structured JSON output`**

```java Structured JSON output
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"responseFormat\": {\n    \"jsonSchema\": {\n      \"properties\": {\n        \"percentChange\": {\n          \"type\": \"number\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"summary\",\n        \"percentChange\"\n      ],\n      \"type\": \"object\"\n    },\n    \"type\": \"json_schema\"\n  }\n}")
  .asString();
```

**`Structured JSON output`**

```php Structured JSON output
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId', [
  'body' => '{
  "messages": [
    {
      "content": "Summarize this month\'s sales trends.",
      "role": "user"
    }
  ],
  "responseFormat": {
    "jsonSchema": {
      "properties": {
        "percentChange": {
          "type": "number"
        },
        "summary": {
          "type": "string"
        }
      },
      "required": [
        "summary",
        "percentChange"
      ],
      "type": "object"
    },
    "type": "json_schema"
  }
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

**`Structured JSON output`**

```csharp Structured JSON output
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"messages\": [\n    {\n      \"content\": \"Summarize this month's sales trends.\",\n      \"role\": \"user\"\n    }\n  ],\n  \"responseFormat\": {\n    \"jsonSchema\": {\n      \"properties\": {\n        \"percentChange\": {\n          \"type\": \"number\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"summary\",\n        \"percentChange\"\n      ],\n      \"type\": \"object\"\n    },\n    \"type\": \"json_schema\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Structured JSON output`**

```swift Structured JSON output
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = [
  "messages": [
    [
      "content": "Summarize this month's sales trends.",
      "role": "user"
    ]
  ],
  "responseFormat": [
    "jsonSchema": [
      "properties": [
        "percentChange": ["type": "number"],
        "summary": ["type": "string"]
      ],
      "required": ["summary", "percentChange"],
      "type": "object"
    ],
    "type": "json_schema"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/agents/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

That request returns a response like the following:

### Response (200)

```json
{
  "object": "agent.run",
  "runId": "018f5a74-2e6f-7c83-b4d2-9a1e5f3c7b62",
  "createdAt": 1716312410,
  "completedAt": 1716312413,
  "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": "{\"summary\":\"Sales grew 8% month-over-month, led by the Northeast region.\",\"percentChange\":8}",
      "role": "assistant"
    }
  ],
  "usage": {
    "turns": 2,
    "durationMs": 2876,
    "inputTokens": 540,
    "outputTokens": 30,
    "totalTokens": 570
  },
  "outputParsed": {
    "percentChange": 8,
    "summary": "Sales grew 8% month-over-month, led by the Northeast region."
  },
  "workbookVersion": 14
}
```

## Related resources

* [About Sigma agents (Beta)](/docs/sigma-agents)
* [Build Sigma agents (Beta)](/docs/build-agents)
* [Chat with Sigma agents (Beta)](/docs/chat-with-agent)
* [Generate API client credentials](/reference/generate-client-credentials)