Cortex Agents REST API¶

The Cortex Data Agent REST API allows you to create, manage, and interact with Cortex Data Agents in your Snowflake account. Use this API to build conversational data applications, automate data analysis, and integrate agent-driven workflows.

Create Cortex Agent¶

POST /api/v2/databases/{database}/schemas/{schema}/agents

Creates a new Cortex Data Agent with the specified attributes and specification.

Request¶

Path parameters¶

Parameter	Description
`database`	(Required) Your Snowflake Account URL.
`schema`	(Required) Schema identifier.

Query parameters¶

Parameter	Description
`createMode`	(Optional) Resource creation mode. Valid values: `errorIfExists` `orReplace` `ifNotExists`

Parameter

Description

createMode

(Optional) Resource creation mode. Valid values:

errorIfExists

orReplace

ifNotExists

Request headers¶

Header	Description
`Authorization`	(Required) Authorization token. For more information, see Authentication.
`Content-Type`	(Required) application/json

Request body¶

The request body defines the agent’s name, profile, model configuration, orchestration, instructions, tools, and tool resources.

Field	Type	Description
`name`	string	(Required) Name of the agent.
`comment`	string	Optional comment about the agent.
profile	object	Agent profile information (display name, avatar, color, etc.).
models	object	Model configuration for the agent. Includes the orchestration model (e.g., `llama3.3-70B`). If not provided, a model is automatically selected.
orchestration	object	Orchestration configuration, including budget constraints (e.g., `seconds`, `tokens`).
instructions	object	Instructions for the agent’s behavior, including response, orchestration, system, and sample questions.
tools	array	List of tools available to the agent. Each tool includes a `tool_spec` with type, name, description, and input schema.
tool_resources	object	Configuration for each tool referenced in the tools array. Keys must match the tool `name`.

profile¶

The profile field configures tool selection behavior.

Field	Type	Description
`display_name`	string	Display name for the agent.
`avatar`	string	Avatar image for the agent.
`color`	string	Color theme for the agent.

models¶

The models field configures models for the agent.

Field	Type	Description
`orchestration`	string	Model to use for orchestration. If not provided, a model is automatically selected.

orchestration¶

The orchestration field configures orchestration settings for the agent.

Field	Type	Description
budget	object	Budget constraints for the agent.

budget¶

The budget object specifies resource limits for the agent.

Field	Type	Description
`seconds`	integer	Time budget in seconds.
`tokens`	integer	Token budget.

instructions¶

The instructions field defines instructions for the agent’s behavior, including response generation, orchestration, system instructions, and sample questions.

Field	Type	Description
`response`	string	Instructions for response generation.
`orchestration`	string	Instructions for orchestrating different tools.
`system`	string	System instructions for the agent.
sample_questions	array	Sample questions and optional answers for the agent.

sample_questions¶

Each element in the sample_questions array is an object with the following fields:

Field	Type	Description
`question`	string	Sample question.
`answer`	string	Optional sample answer.

tools¶

The tools field defines the list of tools available for the agent to use. Tools provide specific capabilities such as data analysis, search, or generic functions. Each tool may have a corresponding configuration in the tool_resources object.

Field	Type	Description
tool_spec	object	(Required) Specification of the tool’s type, configuration, and input requirements.

tool_spec¶

The tool_spec object describes the tool’s capabilities and configuration.

Field	Type	Description
`type`	string	(Required) The type of tool capability. Can be specialized types, such as `cortex_analyst_text_to_sql` or `generic` for general-purpose tools. `cortex_search` `cortex_analyst_text_to_sql` `data_to_chart` `generic`
`name`	string	(Required) Unique identifier for referencing this tool instance. Used to match with configuration in `tool_resources`.
`description`	string	Description of the tool to be considered for tool use.
input_schema	object	JSON Schema definition of the expected input parameters for this tool. Required for generic tools to specify their input requirements.

input_schema¶

The input_schema object defines the input parameters for the tool.

Field	Type	Description
`type`	string	The type of the input schema object.
`properties`	object	Definitions of each input parameter.
`required`	array	List of required input parameter names.

tool_resources¶

The tool_resources object defines configuration for each tool referenced in the tools array. Each key must match the tool name. The value can be one of the following objects:

Cortex Analyst analysis tool configuration¶

Configuration for Cortex Analyst analysis tools. Provides parameters for SQL query generation and execution.

Field	Type	Description
`semantic_model_file`	string	The path to a file stored in a Snowflake Stage holding the semantic model yaml.
`semantic_view`	string	The name of the Snowflake native semantic model object. Example: db.schema.semantic_view

Search tool configuration¶

Configuration for search functionality. Defines how document search and retrieval should be performed.

Field	Type	Description
`search_service`	string	The name of the search service. Must be in the format: database.schema.service_name
`name`	string	Reserved.
`max_results`	integer	The number of search results used in LLM prompt.
`title_column`	string	The title column of the document.
`id_column`	string	The ID column of the document.
`filter`	object	Filter query for search results. The object is composed of a field and value pair.

Both configuration objects allow additional properties.

Example request body¶

{
 "name": "my_agent",
 "comment": "Sample agent",
 "profile": {
  "display_name": "My Data Agent",
  "avatar": "AiIcon",
  "color": "#00AEEF"
 },
 "models": {
  "orchestration": "llama3.3-70B"
 },
 "orchestration": {
  "budget": {
   "seconds": 200,
   "tokens": 5000
   }
  },
 "instructions": {
  "response": "Always provide a concise response and maintain a friendly tone.",
  "orchestration": "<orchestration instructions>",
  "system": "You are a helpful data agent.",
  "sample_questions": [
    {
      "question": "Sample question",
      "answer": "sample answer"
    }
  ]
 },
 "tools": [
  {
   "tool_spec": {
          "description": "Analyst to analyze price",
    "type": "cortex_analyst_text_to_sql",
    "name": "Analyst1"
   }
  },
  {
   "tool_spec": {
    "type": "cortex_search",
    "name": "Search1"
   }
  }
 ],
 "tool_resources": [
  {
    "Search1": {
        "search_service": "db.schema.service_name",
        "filter": {"@eq": {"region": "North America"} },
        "max_results": 5
    }
  },
  {
    "Analyst1": {
     "semantic_view": "my_db.my_sch.my_sem_view_1"
    }
  }
 ]
}

Copy

Response¶

A successful response returns a JSON object with details about the status of Cortex Agent creation.

Response body¶

{"status": "Agent xxxx successfully created."}

Copy

Describe Cortex Agent¶

GET /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Describes a Cortex Agent.

Request¶

Path parameters¶

Parameter	Description
`database`	(Required) Identifier for the database to which the resource belongs. You can use the /api/v2/databases GET request to get a list of available databases.
`schema`	(Required) Identifier for the schema to which the resource belongs. You can use the /api/v2/databases/{database}/schemas GET request to get a list of available schemas for the specified database.
`name`	(Required) Identifier for the agent.

Request headers¶

Header	Description
`Authorization`	(Required) Authorization token. For more information, see Authentication.
`Content-Type`	(Required) application/json

Response¶

A successful response returns a JSON object describing the Cortex Agent.

Response headers¶

Header	Description
`X-Snowflake-Request-ID`	Unique ID of the API request.
`Link`	Links to the page of results (e.g. the first page, the last page, etc.). The header can include multiple url entries with different rel attribute values that specify the page to return (first, next, prev, and last).

Response body¶

The response body contains the details of the Cortex Agent.

{
 "name": "my_agent",
 "database": "TEST_DB",
 "schema": "TEST_SCHEMA",
 "created_on": "2024-06-01T12:00:00Z",
 "owner": "ACCOUNTADMIN",
 "comment": "Sample agent",
 "profile": {
  "display_name": "My Data Agent",
  "avatar": "AiIcon",
  "color": "#00AEEF"
 },
 "models": {
  "orchestration": "llama3.3-70B"
 },
 "instructions": {
  "response": "Always provide a concise response and maintain a friendly tone.",
  "system": "You are a helpful data agent."
 },
 "tools": [
  {
    "tool_spec": {
     "type": "cortex_analyst_text_to_sql",
     "name": "Analyst1"
    }
  }
 ],
}

Copy

Update Cortex Agent¶

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Updates an existing Cortex Agent with the specified attributes and specification.

Request¶

Path parameters¶

Parameter	Description
`database`	(Required) Your Snowflake Account URL. You can use the `/api/v2/databases` GET request to get a list of available databases.
`schema`	(Required) Schema identifier. You can use the `/api/v2/databases/{database}/schemas` GET request to get a list of available schemas for the specified database.
`name`	(Required) Name of the agent.

Request headers¶

Header	Description
`Authorization`	(Required) Authorization token. For more information, see Authentication.
`Content-Type`	(Required) application/json

Request body¶

The request body defines the agent’s name, profile, model configuration, orchestration, instructions, tools, and tool resources.

Field	Type	Description
`comment`	string	Optional comment about the agent.
profile	object	Agent profile information (display name, avatar, color, etc.).
models	object	Model configuration for the agent. Includes the orchestration model (e.g., `llama3.3-70B`). If not provided, a model is automatically selected.
orchestration	object	Orchestration configuration, including budget constraints (e.g., `seconds`, `tokens`).
instructions	object	Instructions for the agent’s behavior, including response, orchestration, system, and sample questions.
tools	array	List of tools available to the agent. Each tool includes a `tool_spec` with type, name, description, and input schema.
tool_resources	object	Configuration for each tool referenced in the tools array. Keys must match the tool `name`.

profile¶

The profile field configures tool selection behavior.

Field	Type	Description
`display_name`	string	Display name for the agent.
`avatar`	string	Avatar image for the agent.
`color`	string	Color theme for the agent.

models¶

The models field configures models for the agent.

Field	Type	Description
`orchestration`	string	Model to use for orchestration. If not provided, a model is automatically selected.

orchestration¶

The orchestration field configures orchestration settings for the agent.

Field	Type	Description
budget	object	Budget constraints for the agent.

budget¶

The budget object specifies resource limits for the agent.

Field	Type	Description
`seconds`	integer	Time budget in seconds.
`tokens`	integer	Token budget.

instructions¶

The instructions field defines instructions for the agent’s behavior, including response generation, orchestration, system instructions, and sample questions.

Field	Type	Description
`response`	string	Instructions for response generation.
`orchestration`	string	Instructions for orchestrating different tools.
`system`	string	System instructions for the agent.
`sample_questions`	array	Sample questions and optional answers for the agent.

sample_questions¶

Each element in the sample_questions array is an object with the following fields:

Field	Type	Description
`question`	string	Sample question.
`answer`	string	Optional sample answer.

tools¶

Field	Type	Description
tool_spec	object	(Required) Specification of the tool’s type, configuration, and input requirements.

tool_spec¶

The tool_spec object describes the tool’s capabilities and configuration.

Field	Type	Description
`type`	string	(Required) The type of tool capability. Can be specialized types, such as `cortex_analyst_text_to_sql` or `generic` for general-purpose tools. `cortex_search` `cortex_analyst_text_to_sql` `data_to_chart` `generic`
`name`	string	(Required) Unique identifier for referencing this tool instance. Used to match with configuration in `tool_resources`.
`description`	string	Description of the tool to be considered for tool use.
input_schema	object	JSON Schema definition of the expected input parameters for this tool. Required for generic tools to specify their input requirements.

input_schema¶

The input_schema object defines the input parameters for the tool.

Field	Type	Description
`type`	string	The type of the input schema object.
`properties`	object	Definitions of each input parameter.
`required`	array	List of required input parameter names.
`example`	object	Examples of omitted input parameters.

tool_resources¶

The tool_resources object defines configuration for each tool referenced in the tools array. Each key must match the tool name. The value can be one of the following objects:

Cortex Analyst analysis tool configuration¶

Configuration for Cortex Analyst analysis tools. Provides parameters for SQL query generation and execution.

Field	Type	Description
`semantic_model_file`	string	The path to a file stored in a Snowflake Stage holding the semantic model yaml.
`semantic_view`	string	The name of the Snowflake native semantic model object. Example: db.schema.semantic_view

Search tool configuration¶

Configuration for search functionality. Defines how document search and retrieval should be performed.

Field	Type	Description
`search_service`	string	The name of the search service. Must be in the format: database.schema.service_name
`name`	string	Reserved.
`max_results`	integer	The number of search results used in LLM prompt.
`title_column`	string	The title column of the document.
`id_column`	string	The ID column of the document.
`filter`	object	Filter query for search results. The object is composed of a field and value pair.

Both configuration objects allow additional properties.

Example request body¶

{
 "name": "my_agent",
 "comment": "Sample agent",
 "profile": {
  "display_name": "My Data Agent",
  "avatar": "AiIcon",
  "color": "#00AEEF"
 },
 "models": {
  "orchestration": "llama3.3-70B"
 },
 "orchestration": {
  "budget": {
   "seconds": 200,
   "tokens": 5000
   }
  },
 "instructions": {
  "response": "Always provide a concise response and maintain a friendly tone.",
  "orchestration": "<orchestration instructions>"
  "system": "You are a helpful data agent."
  "sample_questions": [
    {
      "question": "Sample question",
      "answer": "sample answer"
    }
  ]
 },
 "tools": [
  {
   "tool_spec": {
          "description": "Analyst to analyze price",
    "type": "cortex_analyst_text_to_sql",
    "name": "Analyst1"
   }
  },
  {
   "tool_spec": {
    "type": "cortex_search",
    "name": "Search1"
   }
  }
 ],
 "tool_resources": [
  {
    "Search1": {
        "search_service": "db.schema.service_name",
        "filter": {"@eq": {"region": "North America"} },
        "max_results": 5
    }
  },
  {
    "Analyst1": {
     "semantic_view": "my_db.my_sch.my_sem_view_1"
    }
  }
 ]
}

Copy

Response¶

A successful response returns a JSON object with details about the status of Cortex Agent update.

Response body¶

{"status": "Agent xxxx successfully updated."}

Copy

List Cortex Agents¶

GET /api/v2/databases/{database}/schemas/{schema}/agents

Lists the Cortex Agents under the specified database and schema.

Request¶

Path parameters¶

Parameter	Description
`database`	(Required) Identifier for the database to which the resource belongs. You can use the /api/v2/databases GET request to get a list of available databases.
`schema`	(Required) Identifier for the schema to which the resource belongs. You can use the /api/v2/databases/{database}/schemas GET request to get a list of available schemas for the specified database.

Query parameters¶

Parameter	Description
`like`	(Optional) Filter the output by resource name. Uses case-insensitive pattern matching with support for SQL wildcard characters.
`fromName`	(Optional) Enable fetching rows only following the first row whose object name matches the specified string. Case-sensitive and does not have to be the full name.
`showLimit`	(Optional) Limit the maximum number of rows returned by the command. Minimum: 1. Maximum: 10000.

Request headers¶

Header	Description
`Authorization`	(Required) Authorization token. For more information, see Authentication.
`Content-Type`	(Required) application/json

Response¶

A successful response returns a JSON array of Cortex Agent resources.

Response headers¶

Header	Description
`X-Snowflake-Request-ID`	Unique ID of the API request.
`Link`	Links to the page of results (e.g. the first page, the last page, etc.). The header can include multiple url entries with different rel attribute values that specify the page to return (first, next, prev, and last).

Response body¶

[
 {
  "name": "my_agent",
  "database": "TEST_DB",
  "schema": "TEST_SCHEMA",
  "created_on": "2024-06-01T12:00:00Z",
  "owner": "ACCOUNTADMIN",
  "comment": "Sample agent"
 },
 {
  "name": "another_agent",
  "database": "TEST_DB",
  "schema": "TEST_SCHEMA",
  "created_on": "2024-06-02T08:30:00Z",
  "owner": "SYSADMIN",
  "comment": ""
 }
]

Copy

Delete Cortex Agent¶

DELETE /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Deletes a Cortex Agent with the specified name. If the ifExists parameter is set to true, the operation succeeds even if the agent does not exist. Otherwise, the operation fails if the agent cannot be deleted.

Request¶

Path parameters¶

Parameter	Description
`database`	(Required) Identifier for the database to which the resource belongs. You can use the /api/v2/databases GET request to get a list of available databases.
`schema`	(Required) Identifier for the schema to which the resource belongs. You can use the /api/v2/databases/{database}/schemas GET request to get a list of available schemas for the specified database.
`name`	(Required) Identifier for the agent.

Query parameters¶

Parameter	Description
`ifExists`	(Optional) Specifies how to handle the request if the agent does not exist. `true`: The endpoint does not throw an error if the agent does not exist. It returns a 200 success response, but does not take any action. `false`: The endpoint throws an error if the agent does not exist.

Parameter

Description

ifExists

(Optional) Specifies how to handle the request if the agent does not exist.

true: The endpoint does not throw an error if the agent does not exist. It returns a 200 success response, but does not take any action.
false: The endpoint throws an error if the agent does not exist.

Request headers¶

Header	Description
`Authorization`	(Required) Authorization token. For more information, see Authentication.
`Content-Type`	(Required) application/json

Response¶

A successful response returns a confirmation message.

Response body¶

{
 "status": "Request successfully completed"
}

Copy

Run agent object¶

POST /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run

Sends a user query to the Cortex Agent object and returns its response as a stream of events.

Request¶

Path parameters¶

Parameter	Description
`database`	(Required) The database containing the agent. You can use the `/api/v2/databases` GET request to get a list of available databases.
`schema`	(Required) The schema containing the agent. You can use the `/api/v2/databases/{database}/schemas` GET request to get a list of available schemas for the specified database.
`name`	(Required) The name of the agent.

Request headers¶

Header	Description
`Authorization`	(Required) Authorization token. See Authentication.
`Content-Type`	(Required) application/json

Request body¶

The request body contains the conversation history, tool configuration, and optional execution settings.

Field	Type	Description
`thread_id`	integer	Optional. The thread identifier for the conversation. If `thread_id` is used, then `parent_message_id` must be passed as well.
`parent_message_id`	integer	Optional. The message ID from which this run should begin. The initial `parent_message_id` should be `0`.
messages	array	(Required) If `thread_id` and `parent_message_id` are present, the current user messages in this conversation turn. Else, the conversation history and current message. Contains both user queries and assistant responses in chronological order.
tool_choice	object	Optional. Configures tool selection behavior.

messages¶

The messages array contains the conversation history between the user and assistant. If a thread is used, only user message is needed.

Field	Type	Description
`role`	string	(Required) Identifies who sent the message, either the user or the assistant. User messages typically contain queries, while assistant messages contain responses and tool results. Valid values: `"user"` `"assistant"`
content	array	(Required) Array of content elements making up the message. Can include text, tool results, or custom content types.
`schema_version`	array	Optional. The version of the schema.

Field

Type

Description

role

string

(Required) Identifies who sent the message, either the user or the assistant. User messages typically contain queries, while assistant messages contain responses and tool results.

Valid values:

"user"
"assistant"

content

array

(Required) Array of content elements making up the message. Can include text, tool results, or custom content types.

schema_version

array

Optional. The version of the schema.

Message content structure¶

Each message’s content array can contain multiple content elements with different types.

Field	Type	Description
`type`	string	The content type. Valid values: text thinking tool_use tool_result table chart suggested_queries

Field

Type

Description

type

string

The content type.

Valid values:

text
thinking
tool_use
tool_result
table
chart
suggested_queries

text¶

When type is text:

Field

Type

Description

annotations

array

An array of annotations attached to the text result. Can be either cortex_search_citation or web_search_citation.

is_elicitation

boolean

Whether this text content is the agent asking for more information from the end user.

Field	Type	Description
`annotations`	array	An array of annotations attached to the text result. Can be either cortex_search_citation or web_search_citation.
`is_elicitation`	boolean	Whether this text content is the agent asking for more information from the end user.

cortex_search_citation¶

The cortex_search_citation object contains the following fields:

Field

Type

Description

index

integer

(Required) The index of the citation in the search results.

search_result_id

string

(Required) The unique identifier for the search result.

doc_id

string

(Required) The unique identifier for the document.

doc_title

string

(Required) The title of the document.

text

string

(Required) The text excerpt from the document used as the citation.

Field	Type	Description
`index`	integer	(Required) The index of the citation in the search results.
`search_result_id`	string	(Required) The unique identifier for the search result.
`doc_id`	string	(Required) The unique identifier for the document.
`doc_title`	string	(Required) The title of the document.
`text`	string	(Required) The text excerpt from the document used as the citation.

web_search_citation¶

The web_search_citation object contains the following fields:

Field

Type

Description

start_index

integer

(Required) The starting index of the citation in the text.

end_index

integer

(Required) The ending index of the citation in the text.

source_url

string

(Required) The URL of the source document.

text

string

(Required) The text excerpt from the source used as the citation.

Field	Type	Description
`start_index`	integer	(Required) The starting index of the citation in the text.
`end_index`	integer	(Required) The ending index of the citation in the text.
`source_url`	string	(Required) The URL of the source document.
`text`	string	(Required) The text excerpt from the source used as the citation.

thinking¶

When type is thinking:

Field

Type

Description

type

string

The text content of the message.

thinking

string

Thinking tokens from the agent.

Field	Type	Description
`type`	string	The text content of the message.
`thinking`	string	Thinking tokens from the agent.

tool_use¶

When type is tool_use:

Field

Type

Description

tool_use

object

Container for tool use request details.

tool_use.tool_use_id

string

Unique identifier for this tool use request. Can be used to associated tool results.

tool_use.type

string

The type of the tool. For example, cortex_search or cortex_analyst_text2sql.

tool_use.name

string

The unique identifier for this tool instance.

tool_use.input

object

The structured input for this tool.

Field	Type	Description
`tool_use`	object	Container for tool use request details.
`tool_use.tool_use_id`	string	Unique identifier for this tool use request. Can be used to associated tool results.
`tool_use.type`	string	The type of the tool. For example, `cortex_search` or `cortex_analyst_text2sql`.
`tool_use.name`	string	The unique identifier for this tool instance.
`tool_use.input`	object	The structured input for this tool.

tool_result¶

When type is tool_result:

Field

Type

Description

tool_result

object

(Required) Container for tool execution results and metadata.

tool_result.tool_use_id

string

(Required) Unique identifier for this tool use. Can be used to associated tool results.

tool_result.type

string

(Required) The type of the tool. For example, cortex_search or cortex_analyst_text2sql.

tool_result.name

string

(Required) The unique identifier for this tool instance.

tool_result.status

string

(Required) Tool execution status.

Valid values:

"success"

"error"

tool_result.result

object

Additional result data.

tool_result.content

array

(Required) Array of content elements produced by the tool execution.

Can contain elements of the following types:

Type

Fields

Description

text

type: "text"

text: string

Plain text content returned by the tool.

json

type: "json"

json: object

Structured JSON data returned by the tool. The schema varies depending on the tool type.

table¶

When type is table:

Field

Type

Description

table

object

(Required) The table content of the message.

table.tool_use_id

string

(Required) The ID of the tool use that generated this table.

table.query_id

string

(Required) The query ID of the SQL query that generated this data.

table.result_set

string

(Required) The query ID of the SQL query that generated this data.

table.result_set¶

The ResultSet object represents the result of a SQL query execution. This object matches the schema for ResultSet.

Field

Type

Description

statementHandle

string

(Required) The unique identifier for the executed statement.

resultSetMetaData

object

(Required) Metadata describing the structure of the result set.

data

array of arrays of strings

(Required) The actual result data, represented as an array of rows. Each row is an array of string values.

resultSetMetaData¶

The ResultSetMetaData object describes metadata for a SQL query result set.

Field

Type

Description

partition

integer

(Required) The partition number for the result set.

numRows

integer

(Required) The number of rows in the result set.

format

string

(Required) The format of the result set.

rowType

array

(Required) Array describing the type of each row. Each element is a rowType object.

rowType¶

The RowType object describes the metadata for a single row in a SQL query result set.

Field

Type

Description

name

integer

(Required) The name of the row.

type

integer

(Required) The data type of the row.

length

string

(Required) The length.

precision

array

(Required) The precision.

scale

array

(Required) The scale.

nullable

array

(Required) Indicates whether the row can contain null values.

chart¶

When type is chart:

Field

Type

Description

chart

object

The chart content of the message.

Chart content structure¶

The chart object contains the following fields:

Field

Type

Description

tool_use_id

string

(Required) The ID of the tool use that generated this chart.

chart_spec

string

(Required) The vega-lite chart specification serialized as a string.

analyst_tool_use_id

string

(Deprecated) The tool_use_id of the Cortex Analyst tool call that generated the data for this chart. Clients should use tool_use_id to fetch the chart tool use and from there find the Analyst tool_use_id if needed.

suggested_queries¶

When type is suggested_queries:

Field

Type

Description

suggested_queries

array

(Required) An array of query arrays.

tool_choice¶

The tool_choice object configures how tools should be selected and used during the interaction.

Field

Type

Description

type

string

(Required) Determines how tools are selected:

auto - Automatic tool selection (default)

required - Must use at least one tool

tool - Use specific named tools

name

array of strings

List of specific tool names to use when type is tool.

Example request¶

{
  "thread_id": "1234567890",
  "parent_message_id": "1234567890",
  "tool_choice": {
    "type": "auto"
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What are the top three customers by revenue?"
        }
      ]
    }
  ]
}

Copy

Response¶

When streaming, each event arrives in Server-Sent Events (SSE) format, with the following primary patterns:

response events events when the final response is available. This is the last event emitted, and includes the aggregation of all other events previously streamed.
response.text events events when a text content block is done streaming, including all the aggregated deltas for a particular content index.
response.text.delta events events when a new output text delta is generated.
response.text.annotation events events when an annotation is added to a text content.
response.thinking events events when a thinking content block is done streaming, including all the aggregated deltas for a particular content index.
response.thinking.delta events events when a thinking delta is generated.
response.tool_use events events when the agent requests a tool use.
response.tool_result events events when a tool finishes executing, including the tool result.
response.tool_result.status events events when a status update is available for a specific tool use.
response.tool_result.analyst.delta events events when a Cortex Analyst tool execution delta is generated.
response.table events events when a table content block is added.
response.chart events events when a chart content block is added.
response.status events events when a status update is available for the agent’s execution.
response.suggested_queries events events when a suggested queries content block is added.
error events events if something goes wrong.

`response` events¶

Field	Type	Description
`event`	string	`response` for the final response event.
`data`	object	Contains response data.
`data.role`	string	The role of the message sender. Must be `assistant`.
`data.content`	array	Array of content elements making up the response. The content elements follow the schema for content.

`response.text` events¶

Field	Type	Description
`event`	string	`response.text` for a text content block event.
`data`	object	Contains the text event data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.content`	array	Array of content elements making up the response. The content elements follow the schema for content.
`data.text`	string	A text result from the agent.
`data.annotations`	array	An array of annotations attached to the text result (for example, citations). Can be either cortex_search_citation or web_search_citation.
`data.is_elicitation`	boolean	Whether this text content is the agent asking for more information from the end user.

`response.text.delta` events¶

Field	Type	Description
`event`	string	`response.text.delta` for a text delta event.
`data`	object	Contains the text delta data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.text`	string	A text delta from the agent.
`data.is_elicitation`	boolean	Whether this text content is the agent asking for more information from the end user.

`response.text.annotation` events¶

Field	Type	Description
`event`	string	`response.text.annotation` for an annotation event.
`data`	object	Contains the annotation data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.annotation_index`	integer	The index in the annotation content array that this event represents.
`data.annotations`	array	An array of annotations attached to the text result (for example, citations). Can be either cortex_search_citation or web_search_citation.

`response.thinking` events¶

Field	Type	Description
`event`	string	`response.thinking` for a thinking content block event.
`data`	object	Contains the thinking content block data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.text`	string	Thinking tokens from the agent.

`response.thinking.delta` events¶

Field	Type	Description
`event`	string	`response.thinking.delta` for a thinking delta event.
`data`	object	Contains the thinking delta data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.text`	string	The thinking token.

`response.tool_use` events¶

Field	Type	Description
`event`	string	`response.tool_use` for a thinking content block event.
`data`	object	Contains the tool use request data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.text`	string	Thinking tokens from the agent.
`data.tool_use_id`	string	Unique identifier for this tool use.
`data.type`	string	The type of the tool.
`data.name`	string	The unique identifier for this tool instance.
`data.input`	object	The structured input for this tool. The schema of this object will vary depending on the tool specification.

`response.tool_result` events¶

Field	Type	Description
`event`	string	`response.tool_result` for a tool result event.
`data`	object	Contains the tool result data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.text`	string	Thinking tokens from the agent.
`data.tool_use_id`	string	Unique identifier for this tool use.
`data.type`	string	The type of the tool.
`data.name`	string	The unique identifier for this tool instance.
`data.content`	array	Array of content elements produced by the tool execution. Each element follows the tool_result schema.

`response.tool_result.status` events¶

Field	Type	Description
`event`	string	`response.tool_result.status` for a tool result status event.
`data`	object	Contains the tool result status data.
`data.tool_use_id`	string	Unique identifier for this tool use.
`data.tool_type`	string	The type of the tool.
`data.status`	string	Enum for the current state.
`data.message`	string	A more descriptive message expanding on the current status.

`response.tool_result.analyst.delta` events¶

Field	Type	Description
`event`	string	`response.tool_result.analyst.delta` for a Cortex Analyst tool execution delta event.
`data`	object	Contains the Cortex Analyst tool execution delta data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.tool_use_id`	string	Unique identifier for this tool use. Can be used to associate tool results.
`data.tool_type`	string	The type of the tool (always cortex_analyst_text2sql for this event).
`data.tool_name`	string	The unique identifier for this tool instance.
`data.delta`	object	The delta result for the Cortex Analyst tool execution.
`data.delta.text`	string	A text delta from Cortex Analyst’s final response.
`data.delta.think`	string	A text delta from Cortex Analyst’s reasoning steps.
`data.delta.sql`	string	A delta from Cortex Analyst’s SQL output. Currently, the entire SQL query comes in a single event.
`data.delta.sql_explanation`	string	A delta from Cortex Analyst’s explanation of what the SQL query does.
`data.delta.query_id`	string	The query id after SQL execution begins.
`data.delta.verified_query_used`	boolean	Whether a verified query was used to generate this response.
`data.delta.result_set`	object	The results from SQL execution. Matches the schema from Snowflake’s SQL API ResultSet. See Snowflake SQL API reference.
`data.delta.suggestions`	object	A delta from Cortex Analyst’s suggested questions. This is sent when Analyst cannot answer the question due to missing information or other failures.
`data.delta.suggestions.index`	object	The index of the suggestion array this delta represents.
`data.delta.suggestions.delta`	object	The text delta for the suggestion in this index.

`response.table` events¶

Field	Type	Description
`event`	string	`response.table` for a table content block event.
`data`	object	Contains the table content block event data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.tool_use_id`	string	The ID of the tool use that generated this table.
`data.query_id`	string	The query id of the SQL query that generated this data.
`data.result_set`	object	The result set for this table. Follows the schema of table.result_set.
`data.title`	string	The title for this table.

`response.chart` events¶

Field	Type	Description
`event`	string	`response.table` for a chart content block event.
`data`	object	Contains the chart content block event data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.tool_use_id`	string	The ID of the tool use that generated this chart.
`data.chart_spec`	string	The vega-lite chart specification serialized as a string.
`data.analyst_tool_use_id`	object	The tool use ID of the Cortex Analyst tool call that generated the data for this chart. This is deprecated. Clients should use `tool_use_id` to fetch the chart tool use and from there find the Analyst `tool_use_id` if needed.

`response.status` events¶

Field	Type	Description
`event`	string	`response.status` for a status update event.
`data`	object	Contains the status update event data.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.status`	string	Enum for the current state.
`data.message`	string	A more descriptive message expanding on the current status.

`response.suggested_queries` events¶

Field	Type	Description
`event`	string	`response.suggested_queries` for a suggested query content block event.
`data`	object	Contains the suggested query content block event data.
`data.status`	string	Enum for the current state.
`data.content_index`	integer	The index in the response content array that this event represents.
`data.suggested_queries`	array	An array of suggested queries. See suggested_queries.

`error` events¶

Field	Type	Description
`event`	string	`error` for error events.
`data`	object	Contains error details.
`data.code`	string	The Snowflake error code. For example, `"399505"`.
`data.message`	string	A description of what went wrong. For example, `"Internal server error"`.

Error responses¶

The API returns standard error responses for invalid requests, unauthorized access, forbidden actions, not found, method not allowed, timeouts, conflicts, and server errors. Each error response includes a message, code, and request ID.

Example response¶

event: response.status
data: {"message":"Planning the next steps","status":"planning"}

event: response.thinking.delta
data: {"content_index":0,"text":"\nThe user is asking for a"}

event: response.thinking.delta
data: {"content_index":0,"text":" chart showing the"}

...
...
...

event: response.status
data: {"message":"Reviewing the results","status":"reasoning_agent_stop"}

event: response.status
data: {"message":"Forming the answer","status":"proceeding_to_answer"}

event: done
data: [DONE]

Copy

Run without agent object¶

POST <account_url>/api/v2/cortex/agent:run

Sends a user query to the Cortex Agents service provided in the request body and returns its response. Interacts with the agent without creating an agent object.

Request¶

Path parameters¶

Parameter	Description
`account_url`	(Required) Your Snowflake Account URL. For instructions on finding your account URL, see Finding the organization and account name for an account.

Request headers¶

Header	Description
`Authorization`	(Required) Authorization token. For more information, see Authentication.
`Content-Type`	(Required) application/json

Request body¶

The request body contains the model, response instruction, experimental fields, tools, tool resources, and messages.

Field	Type	Description
models	object	Model configuration for the agent. Includes the orchestration model (e.g., `llama3.3-70B`). If not provided, a model is automatically selected.
orchestration	object	Orchestration configuration, including budget constraints (e.g., `seconds`, `tokens`).
instructions	object	Instructions for the agent’s behavior, including response, orchestration, system, and sample questions.
messages	array	(Required) If `thread_id` and `parent_message_id` are present, the current user messages in this conversation turn. Else, the conversation history and current message. Contains both user queries and assistant responses in chronological order.
`thread_id`	integer	Optional. The thread identifier for the conversation. If `thread_id` is used, then `parent_message_id` must be passed as well.
`parent_message_id`	integer	Optional. The message ID from which this run should begin. The initial `parent_message_id` should be `0`.
`experimental`	object	Experimental flags passed to the agent.
tools	array	An array of tool specifications available to the agent.
tool_resources	object	Resources required by the tools.
tool_choice	object	The configuration used to select the tool.

Tool specifications¶

The tools field contains an array of tool_spec objects that define the available tools:

Field	Type	Description
`tool_spec.type`	string	The type of tool. A combination of type and name is a unique identifier. Valid values: `cortex_search`: Used for Cortex search functionality `cortex_analyst_text_to_sql`: Used for Cortex Analyst text-to-SQL
`tool_spec.name`	string	The name of the tool. A combination of type and name is a unique identifier.
`tool_spec.description`	string	The name of the tool. A combination of type and name is a unique identifier.
tool_spec.input_schema	string	The name of the tool. A combination of type and name is a unique identifier.

input_schema¶

The input_schema object defines the input parameters for the tool.

Field	Type	Description
`type`	string	The type of the input schema object.
`properties`	object	Definitions of each input parameter.
`required`	array	List of required input parameter names.

Tool choice¶

The tool_choice field configures tool selection behavior.

Field

Type

Description

type

string

How tools should be selected.

Valid values:

"auto"` (default)
"required" (use at least one tool)
"tool" (use specified tool)

name

array

Optional array of tool names to use. Only valid when type = "tool".

Response¶

When streaming, each event arrives in Server-Sent Events (SSE) format, with the following primary patterns:

response events events when the final response is available. This is the last event emitted, and includes the aggregation of all other events previously streamed.
response.text events events when a text content block is done streaming, including all the aggregated deltas for a particular content index.
response.text.delta events events when a new output text delta is generated.
response.text.annotation events events when an annotation is added to a text content.
response.thinking events events when a thinking content block is done streaming, including all the aggregated deltas for a particular content index.
response.thinking.delta events events when a thinking delta is generated.
response.tool_use events events when the agent requests a tool use.
response.tool_result events events when a tool finishes executing, including the tool result.
response.tool_result.status events events when a status update is available for a specific tool use.
response.tool_result.analyst.delta events events when a Cortex Analyst tool execution delta is generated.
response.table events events when a table content block is added.
response.chart events events when a chart content block is added.
response.status events events when a status update is available for the agent’s execution.
response.suggested_queries events events when a suggested queries content block is added.
error events events if something goes wrong.

Cortex Agents limitations¶

Because Streamlit in Snowflake (SiS) apps run under owner’s rights, executing SQL statements within SiS apps is not supported.
Azure OpenAI models are not supported.

Field	Type	Description
`table`	object	(Required) The table content of the message.
`table.tool_use_id`	string	(Required) The ID of the tool use that generated this table.
`table.query_id`	string	(Required) The query ID of the SQL query that generated this data.
`table.result_set`	string	(Required) The query ID of the SQL query that generated this data.

Field	Type	Description
`statementHandle`	string	(Required) The unique identifier for the executed statement.
resultSetMetaData	object	(Required) Metadata describing the structure of the result set.
`data`	array of arrays of strings	(Required) The actual result data, represented as an array of rows. Each row is an array of string values.

Field	Type	Description
`partition`	integer	(Required) The partition number for the result set.
`numRows`	integer	(Required) The number of rows in the result set.
`format`	string	(Required) The format of the result set.
`rowType`	array	(Required) Array describing the type of each row. Each element is a rowType object.

Field	Type	Description
`name`	integer	(Required) The name of the row.
`type`	integer	(Required) The data type of the row.
`length`	string	(Required) The length.
`precision`	array	(Required) The precision.
`scale`	array	(Required) The scale.
`nullable`	array	(Required) Indicates whether the row can contain null values.

Field	Type	Description
`tool_use_id`	string	(Required) The ID of the tool use that generated this chart.
`chart_spec`	string	(Required) The vega-lite chart specification serialized as a string.
`analyst_tool_use_id`	string	(Deprecated) The `tool_use_id` of the Cortex Analyst tool call that generated the data for this chart. Clients should use `tool_use_id` to fetch the chart tool use and from there find the Analyst `tool_use_id` if needed.