Run an agent

curl --request POST \
  --url https://agents.nanonets.com/api/v1/agents/{agent_id}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'query=<string>' \
  --form 'files=<string>' \
  --form 'output_config=<string>' \
  --form version=123 \
  --form 'source=<string>' \
  --form files.items='@example-file'

import requests

url = "https://agents.nanonets.com/api/v1/agents/{agent_id}/run"

files = { "files.items": ("example-file", open("example-file", "rb")) }
payload = {
    "query": "<string>",
    "files": "<string>",
    "output_config": "<string>",
    "version": "123",
    "source": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('query', '<string>');
form.append('files', '<string>');
form.append('output_config', '<string>');
form.append('version', '123');
form.append('source', '<string>');
form.append('files.items', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://agents.nanonets.com/api/v1/agents/{agent_id}/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://agents.nanonets.com/api/v1/agents/{agent_id}/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"version\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://agents.nanonets.com/api/v1/agents/{agent_id}/run"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"version\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://agents.nanonets.com/api/v1/agents/{agent_id}/run")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"version\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://agents.nanonets.com/api/v1/agents/{agent_id}/run")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"version\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

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

{
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "outcome": "terminal",
  "message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "wait_budget_seconds": 123,
  "result_selector": "<string>",
  "result_status": "completed",
  "result": "<unknown>",
  "result_bytes": 123,
  "result_metadata": "<unknown>",
  "output_files": [
    {
      "name": "<string>",
      "url": "<string>",
      "expires_at": 123
    }
  ]
}

{
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "message": "<string>",
  "created_at": "2023-11-07T05:31:56Z"
}

{
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "outcome": "terminal",
  "message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "wait_budget_seconds": 123,
  "result_selector": "<string>",
  "result_status": "completed",
  "result": "<unknown>",
  "result_bytes": 123,
  "result_metadata": "<unknown>",
  "output_files": [
    {
      "name": "<string>",
      "url": "<string>",
      "expires_at": 123
    }
  ]
}

{
  "error": "Invalid agent_id format"
}

{
  "error": "Invalid agent_id format"
}

{
  "error": "Invalid agent_id format"
}

{
  "error": "Invalid agent_id format"
}

{
  "error": "Invalid agent_id format"
}

Agents

Run an agent

Create a new task for the specified agent. Two body formats are accepted:

multipart/form-data — when you need to attach files (PDFs, images, spreadsheets, etc.). Send one files part per attachment, plus optional query and output_config (the latter as a JSON-encoded string field).
application/json — for text-only runs. Send query and an optional structured output_config object.

Either query or at least one file must be provided.

The response returns immediately with the new task_id. The task itself runs asynchronously — poll GET /v1/tasks/{task_id} or GET /v1/tasks/{task_id}/summary to retrieve the result.

POST

api

agents

{agent_id}

run

Run an agent

curl --request POST \
  --url https://agents.nanonets.com/api/v1/agents/{agent_id}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'query=<string>' \
  --form 'files=<string>' \
  --form 'output_config=<string>' \
  --form version=123 \
  --form 'source=<string>' \
  --form files.items='@example-file'

import requests

url = "https://agents.nanonets.com/api/v1/agents/{agent_id}/run"

files = { "files.items": ("example-file", open("example-file", "rb")) }
payload = {
    "query": "<string>",
    "files": "<string>",
    "output_config": "<string>",
    "version": "123",
    "source": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('query', '<string>');
form.append('files', '<string>');
form.append('output_config', '<string>');
form.append('version', '123');
form.append('source', '<string>');
form.append('files.items', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://agents.nanonets.com/api/v1/agents/{agent_id}/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://agents.nanonets.com/api/v1/agents/{agent_id}/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"version\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://agents.nanonets.com/api/v1/agents/{agent_id}/run"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"version\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://agents.nanonets.com/api/v1/agents/{agent_id}/run")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"version\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://agents.nanonets.com/api/v1/agents/{agent_id}/run")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"query\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"output_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"version\"\r\n\r\n123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"source\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

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

{
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "outcome": "terminal",
  "message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "wait_budget_seconds": 123,
  "result_selector": "<string>",
  "result_status": "completed",
  "result": "<unknown>",
  "result_bytes": 123,
  "result_metadata": "<unknown>",
  "output_files": [
    {
      "name": "<string>",
      "url": "<string>",
      "expires_at": 123
    }
  ]
}

{
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "message": "<string>",
  "created_at": "2023-11-07T05:31:56Z"
}

{
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "outcome": "terminal",
  "message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "wait_budget_seconds": 123,
  "result_selector": "<string>",
  "result_status": "completed",
  "result": "<unknown>",
  "result_bytes": 123,
  "result_metadata": "<unknown>",
  "output_files": [
    {
      "name": "<string>",
      "url": "<string>",
      "expires_at": 123
    }
  ]
}

{
  "error": "Invalid agent_id format"
}

{
  "error": "Invalid agent_id format"
}

{
  "error": "Invalid agent_id format"
}

{
  "error": "Invalid agent_id format"
}

{
  "error": "Invalid agent_id format"
}

Authorizations

Authorization

string

header

required

Workspace API key issued from the web app. Pass as Authorization: Bearer YOUR_API_KEY.

Path Parameters

agent_id

string<uuid>

required

UUID of the agent.

Query Parameters

async

boolean

default:true

false holds the request open until the run finishes and returns the result on this call. A non-boolean value is rejected with 400 rather than treated as the default — a typo must not silently behave differently from what you asked for.

When the synchronous path is unavailable the request behaves exactly as async=true and answers 201, with X-Sync-Budget-Seconds: 0 so you can tell that case apart. That happens when the feature is off for the environment or the agent, when the run was queued behind the agent's concurrency limit, or when this instance is already holding its maximum number of requests.

result

string

Which payload async=false returns. Required when async=false, unless the agent carries a settings.sync_result default. There is no implicit default: the only sensible one to pick would be the largest payload and the only one that can exceed the response limit.

Value	Returns	Same payload as
`feed`	The whole transcript	`GET /v1/tasks/{task_id}/result`
`summary`	The final answer	`GET /v1/tasks/{task_id}/summary`
`structured`	The structured output	`GET /v1/tasks/{task_id}/structured-response`
`tool:<tool_name>`	One tool's output	`GET /v1/tasks/{task_id}/tool-result`

An explicit result=structured on an agent with no output schema is rejected with 400 before the run is created, since nothing could ever produce one. An agent whose STORED settings.sync_result is structured degrades to the transcript instead, so one bad setting cannot fail every synchronous run for that agent.

Body

query

string

Prompt text. Optional when one or more files are attached.

files

file[]

One or more file attachments (PDF, image, Word, Excel, etc.). Repeat the files field per attachment. The legacy field name file is also accepted for a single upload.

output_config

string

JSON-encoded TaskOutputConfig — submitted as a string field in multipart bodies. Supports output_schema and instructions. See the RunAgentRequest schema for the structured equivalent.

version

integer

Optional. Run a specific published version. See the RunAgentRequest schema.

source

string

Optional. production (default) or test. See the RunAgentRequest schema.

Response

The run reached a terminal state within the wait budget. A run that failed or was stopped is still a 200: the HTTP call did what it was asked, and a 5xx would invite retries of a run that failed for a legitimate reason.

The async=false reply: RunAgentResponse's fields plus the run's result and the budget that was applied.

task_id

string<uuid>

required

agent_id

string<uuid>

required

status

enum<string>

required

Lifecycle status of a task.

pending — created, not yet picked up
queued — held back by admission control (agent at concurrent-task limit)
running — being processed by the worker
waiting_for_input — agent called ask_user; reply with POST /tasks/{id}/message
awaiting_review — agent is paused for human approval of a sensitive step
completed — terminal: finished successfully
failed — terminal: errored out
stopped — terminal: cancelled by a user or system

Available options:

pending,

queued,

running,

waiting_for_input,

awaiting_review,

completed,

failed,

stopped

outcome

enum<string>

required

Why this reply was produced, in a form you can branch on. Three situations answer 202 and they call for different handling.

Value	Status	Meaning
`terminal`	200	The run finished; its result is in this reply.
`budget_expired`	202	Still running. Poll for it.
`draining`	202	The server began shutting down and released the hold early. The run continues; do not retry it.
`result_unavailable`	202	The run finished but its result could not be read. Fetch it rather than keep waiting.

Treat an unrecognised value as budget_expired: the run is still collectable by task_id, and new members may be added.

Available options:

terminal,

budget_expired,

draining,

result_unavailable

message

string

required

Human-readable hint. Branch on outcome and result_status, not on this.

created_at

string<date-time>

required

wait_budget_seconds

integer

required

result_selector

string

Which payload was actually applied, after request then agent-setting precedence.

result_status

enum<string>

Why result is what it is. not_found means the run genuinely produced no such payload; unavailable means it could not be read. New members may be added — treat an unrecognised value as unavailable, never as "the agent produced nothing".

Available options:

completed,

not_found,

processing,

failed,

cancelled,

unreadable,

unavailable,

too_large

result

any

The selected payload in its own shape, or absent. Never a substitute object explaining its own absence; result_status and result_bytes carry that.

result_bytes

integer

The payload's real size, set when it was omitted for exceeding the response limit.

result_metadata

any

Sibling metadata for tool:<name> on extraction tools, currently resolved applied_memories.

output_files

object[]

Show child attributes