Skip to main content
POST
/
v1
/
agents
/
runs
cURL
curl --request POST \
  --url https://api.you.com/v1/agents/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent": "advanced",
  "input": "You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common source and dosage of microplastics are. High-light what a safe dosage might be and how to achieve it"
}'
{
  "output": [
    {
      "type": "chat_node.answer",
      "text": "What Engineers Need to Know. **Key Takeaway:**   Microplastics are tiny plastic particles that are pervasive in the environment and can enter the human body through various [...]",
      "content": "You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common source and dosage of microplastics are. High-light what a safe dosage might be and how to achieve it",
      "agent": "advanced"
    }
  ]
}

​
Description

This endpoint engages advanced agents that use tools, multi-turn reasoning, and planning to solve complex queries. The agents break down each query into a workflow, execute the steps iteratively, and reflect on the findings before generating a final response.

​
Streaming Example (SSE)

curl -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -X POST https://api.you.com/v1/agents/runs \
  -d '{
    "agent": "advanced",
    "input": "You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common source and dosage of microplastics are. High-light what a safe dosage might be and how to achieve it",
    "stream": true
  }'
Summary excerpt of streaming events: 
id: 0
event: response.created
data: {"seq_id": 0, "type": "response.created"}

id: 1
event: response.starting
data: {"seq_id": 1, "type": "response.starting"}

id: 2
event: response.output_item.added
data: {"seq_id": 2, "type": "response.output_item.added", "response": {"output_index": 0}}

id: 3
event: response.output_text.delta
data: {"seq_id": 3, "type": "response.output_text.delta", "response": {"output_index": 0, "type": "message.answer", "delta": "## \ud83e\uddec Microplastics: What Engineers Need to Know\n\n---\n\n> **Key Takeaway:**  \n> Microplastic"}}

id: 4
event: response.output_text.delta
data: {"seq_id": 4, "type": "response.output_text.delta", "response": {"output_index": 0, "type": "message.answer", "delta": "s are tiny plastic particles that are pervasive in the environment and can enter the human body through various"}}

id: 5
event: response.output_text.delta
data: {"seq_id": 5, "type": "response.output_text.delta", "response": {"output_index": 0, "type": "message.answer", "delta": " routes. While the full health impacts are still being studied, minimizing exposure is recommended due"}}


// Omitted for brevity


id: 58
event: response.output_text.delta
data: {"seq_id": 58, "type": "response.output_text.delta", "response": {"output_index": 0, "type": "message.answer", "delta": " safe exposure level, engineers and the public can take practical steps to reduce intake and support systemic"}}

id: 59
event: response.output_text.delta
data: {"seq_id": 59, "type": "response.output_text.delta", "response": {"output_index": 0, "type": "message.answer", "delta": " solutions. Ongoing research and innovation\u2014especially in materials science, filtration, and waste management\u2014will be cru"}}

id: 60
event: response.output_text.delta
data: {"seq_id": 60, "type": "response.output_text.delta", "response": {"output_index": 0, "type": "message.answer", "delta": "cial in addressing this emerging challenge.\n\n---\n\n> **Engineers play a vital role in developing solutions to r"}}

id: 61
event: response.output_text.delta
data: {"seq_id": 61, "type": "response.output_text.delta", "response": {"output_index": 0, "type": "message.answer", "delta": " protect public health.**"}}

id: 62
event: response.output_item.done
data: {"seq_id": 62, "type": "response.output_item.done", "response": {"output_index": 0}}

id: 63
event: response.done
data: {"seq_id": 63, "type": "response.done", "response": {"run_time_ms": "29.862", "finished": true}}

Authorizations

​
Authorization
string
header
required

The unique API Key required to authorize API access. Learn how to get yours in the “Get your API key” section of the documentation.

Body

application/json
​
agent
string
default:advanced
required

The agent mode that will be used to execute your request. This parameter must be set as 'advanced'.

​
input
string
required

The input for the agent. This can be a query or a prompt.

Example:

"You are a biologist studying the impacts of microplastics. Explain what microplastics are to a group of engineers, explain the impacts of microplastics on the body, and what the common source and dosage of microplastics are. High-light what a safe dosage might be and how to achieve it"

​
stream
boolean
default:true

When set to "true", it will enable SSE (server side events) response. This is useful if you want to stream the response to your applications (e.g., with chatbots). Currently, only "true" is supported.

​
tools
object[]

Add tools the system can call to expand its capabilities, providing more precise answers to the input query. See Research Tool and Compute Tool for more details.

​
verbosity
enum<string>
default:medium

Controls the level of detail provided by the agent's response. Choosing high maps to a long-form report while medium maps to a medium verbosity report that captures most details but less comprehensive

Available options:
medium,
high
​
workflow_config
object

Manages the parameters that control how the agent orchestrates and executes the workflow to answer your query. Adjust its settings to balance between response quality, thoroughness, and speed.

Response

Inference response in application/json or text/event-stream format.

​
output
object[]
⌘I