Skip to main content
POST
/
v1
/
agents
/
runs
Run a Custom Agent
curl --request POST \
  --url https://api.you.com/v1/agents/runs \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent": "550e8400-e29b-41d4-a716-446655440000",
  "input": "Summarize today'\''s top AI research headlines and cite sources.",
  "stream": false
}'
{
  "output": [
    {
      "type": "web_search.results, chat_node.answer",
      "text": "Here are today's top AI research headlines...",
      "content": "Summarize today's top AI research headlines and cite sources.",
      "agent": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
WARNING: Access to this endpoint requires a paid subscription plan.

​
Description

This endpoint lets you run an assistant you can configure in the UI. Users can create a custom AI agent by providing a description of the desired functionality using natural language. The system supports both conversational inputs and advanced prompting techniques to define the agent’s behavior.

​
Enterprise Settings

To maintain enterprise security, enable Zero Data Retention on your enterprise account. Manage this setting at you.com/settings/privacy. When enabled, the platform does not retain your data and does not use customer data for model training.
WARNING: Privacy settings can only be managed by You.com Enterprise or team admins.

​
Get Your Custom Agent ID

Visit you.com/agents and create a new custom agent with your personalized parameters:New agent settings for custom agents in you.comYou also need to choose whether to enable the tools or not:New agent settings for custom agents in you.com
NOTE: You can manage the tools only in the UI by enabling or disabling them. They can not be managed via the API.See Web Search Tool, Research Tool, and Compute Tool to learn more about tools.
The platform automatically populates the Agents section with all of the agents you’ve created. This is where you can retrieve each agent’s ID:The agent's ID in custom agent in you.comPaste the ID in the agent parameter to call it via API.

​
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": "your_agent_ID",
    "input": "Summarize today\'s top AI research headlines and cite sources.",
    "stream": true
  }'
Small excerpt of streaming events:
id: 0
event: response.output_item.added
data: {"seq_id":0,"type":"response.output_item.added","response":{"type":"chat_node.answer","output_index":0,"delta":"The capital of France is Pa"}}

id: 1
event: response.output_item.delta
data: {"seq_id":1,"type":"response.output_item.delta","response":{"output_index":0,"delta":"ris."}}

​
Limitations

WARNING: The API currently does not support custom agents that use a foundational model with advanced research and reasoning enabled.
WARNING: Files attached to a Custom Agent are not accessible when the agent is invoked via the API.

​
Errors

Errors are returned as a structured JSON object with status, code, title, and detail fields:
HTTPCodeWhen it happens
400bad_requestInvalid request body (e.g., tools must be an array of objects)
401unauthorizedMissing or invalid Authorization header (use a valid <API_KEY>)
403forbiddenYou are not allowed to run this agent or the requested tool
404agent_not_found, agent_not_supported_yetThe agent ID does not exist (or was deleted), or the agent uses an unsupported model/feature

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
required

The custom agent that will be used to execute your request.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
input
required

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

Example:

"Summarize today's top AI research headlines and cite sources."

​
stream
boolean
default:false

When true, responses stream over SSE (text/event-stream). When false, returns JSON (application/json).

Response

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

​
output
object[]
⌘I