The Agents API has six routes under https://api.hercules.app/v1/agents. Every request sends a credential as Authorization: Bearer <credential> and the Hercules-Version header.
| Method | Path | What it does |
|---|---|---|
POST | /v1/agents/{agent_id}/runs | Start a run on a new or existing thread |
GET | /v1/agents/runs/{run_id} | Read a run |
GET | /v1/agents/runs/{run_id}/events | Replay or stream a run's events |
POST | /v1/agents/runs/{run_id}/cancel | Stop a run |
GET | /v1/agents/threads/{thread_id}/messages | Read a thread's messages |
DELETE | /v1/agents/threads/{thread_id} | Delete a thread |
- Only the events route answers calls from a page on another domain, and takes a run token. The others are for your server, with an app key or an Organization API key, and answer a run token with 401
credential_required - No route lists threads or runs. Store the ids you want to read again
- An
agent_idis a ULID in uppercase. Arun_idorthread_idyou choose is a UUID or a ULID. A UUID is taken in either case and kept in lowercase, so answers and events always carry it in lowercase. A ULID must be in uppercase: one in lowercase is a 400invalid_request
Start a run
POST /v1/agents/{agent_id}/runs
| Field | Type | Required | Description |
|---|---|---|---|
run_id | string | No | A UUID or ULID. It is also the idempotency key. Hercules makes one when you leave it out |
thread_id | string | No | Leave it out to open a new thread. A new UUID or ULID opens a thread under that id |
end_user | object | No | The signed-in user the run is for: { "token_identifier": "<issuer>|<subject>" }. Leave it out for your app's own jobs. Only an app key can send it |
input | array | Yes | Content parts. Only { "type": "text", "text": "..." } for now. Anything else is a 400 unsupported_content |
context | object | No | Named JSON values about the page, added to the input. They count toward the size limit |
page_actions | string[] | No | The page actions this page can run. Each must be declared on the Agent, or the request is a 400 invalid_request. The Agent can call only these |
expose_tool_details | boolean | No | Default false. Whether the run's token may read, on the live stream, the names and summaries of Hercules tools and the results of your app tools. See Run events |
wait_seconds | integer | No | 0 to 60, default 0. How long to wait for the run to finish before answering |
It answers 202 while the run is still going, or 200 when it finished within wait_seconds. run is the whole Run, shortened here:
{
"run": { "id": "01JDX4M2...", "thread_id": "01JDX4M1...", "status": "queued" },
"live": {
"url": "https://api.hercules.app/v1/agents/runs/01JDX4M2.../events",
"token": "hrt_..."
}
}- The same
run_idwith the same request returns the run it started, with the samelive.token, and starts nothing. A differentwait_secondsis still the same request. The samerun_idwith a different request is a 409run_id_conflict - A thread answers only to the end user who opened it, on the Agent it was opened on. Anyone else gets a 404
- A thread runs one run at a time. Starting another while one is going is a 409
thread_busy - Do not send a deleted thread's id again. The API does not refuse it: it opens a new, empty thread under the id, so anything that still holds the id would point at a different conversation.
@usehercules/agentsretires the id for you, and refuses it withthread_deleted - Do not send a
run_idagain once its thread is deleted. Deleting a thread deletes its runs, so the id no longer names one: the request is not a retry anymore, and starts a new run with a newlive.token, on a new thread unless it names one token_identifieris<issuer>|<subject>, the user'stokenIdentifierin Convex. It reaches your app tools as a user only when your app's own Hercules Auth issued it. Otherwise the user still has their own threads and limits, but the run acts for no end user- With an Organization API key,
end_useris a 400invalid_request - With an app key, your app must use Hercules Auth 2.0. Hercules signs the run's event deliveries and its app tool calls with your app's own Hercules Auth, so an app without it could not hear from the run. The request is a 409
hercules_auth_required, and nothing is started or charged. Upgrade the app, then send the request again. An Organization API key has no app to deliver to, so it is not held to this - A 503
service_unavailablewithdetails.run_idanddetails.thread_idmeans the run was created, but Hercules could not confirm that it started. It stays queued. Send the same request again with thatrun_idandthread_idafterRetry-After(2 seconds): it starts the run or returns it started, and charges nothing more. Therun_idalone is enough, but without it the retry starts a second run. So always retry a 503 here with the samerun_id
Read a run
GET /v1/agents/runs/{run_id} returns the Run. An app key reads the runs its app started. An Organization API key reads any run of your Organization's Agents.
Read a run's events
GET /v1/agents/runs/{run_id}/events
| Query | Description |
|---|---|
after | An event's seq, 0 to 2147483647. Default 0, the start of the run |
limit | 1 to 100, default 100. JSON only |
Accept | Credential | Answer |
|---|---|---|
application/json | App key or Organization API key | { "data": Event[], "has_more": false }: the durable events after after, oldest first |
text/event-stream | Any, including the run's token | Every event after after or Last-Event-ID, live, until the run's final event |
- A run token sent for
application/jsonis a 401invalid_run_token - On a stream, the
Last-Event-IDheader wins overafter. Either one that is not a whole number from 0 to 2147483647 is a 400invalid_request - A cursor at or past a finished run's last event still gets an answer. The stream sends the run's
message.completed, when it has one, and its final event again. JSON answers an empty page - A stream closes after 10 minutes at most. Reconnect with
Last-Event-ID - A run takes 10 streams at once, however many tokens or keys open them. One more is a 429
rate_limitedwithRetry-After: 5, until a stream closes
The events and the stream are in Run events.
Cancel a run
POST /v1/agents/runs/{run_id}/cancel stops the run and returns the Run. What the run finished before the stop is kept; text still being written when it stops may not be, so output can be null. A stopped step's partial text is not charged. The run usually reads cancelled in the answer. If it still reads queued or running, read it again. Canceling a run that already ended changes nothing.
Read a thread's messages
GET /v1/agents/threads/{thread_id}/messages returns { "data": Message[], "has_more": false }, newest first. Page it with limit (1 to 100, default 100), starting_after, and ending_before, which take message ids.
- Each run adds its input as a
usermessage when it starts, and the reply it finished with as anassistantmessage when it ends. A run that is stillqueuedhas no message here yet, and one that is still going has no reply - A
usermessage holds the input text, without thecontextsent with it
Delete a thread
DELETE /v1/agents/threads/{thread_id} stops a run that is still going and waits up to 5 seconds for it to end. Then it deletes the thread's messages, runs, and events, and revokes its run tokens. It answers:
{ "id": "01JDX4M1...", "deleted": true }- If the run is still stopping after those 5 seconds, the answer is a 409
thread_busywith aRetry-Afterheader, and nothing was deleted. Send the same request again after that many seconds. It succeeds once the run has ended - The 5 seconds are the wait for the run only. The deleting comes after it and takes time of its own, so give the request a timeout of at least 30 seconds
- This can't be undone
- Do not use the thread's id again, or the
run_idof any of its runs. See Start a run
@usehercules/agents does the retrying for you: its deleteThread removes the thread from your app at once, and keeps asking Hercules in the background. See Convex backend.
The Run object
{
"id": "01JDX4M2...",
"thread_id": "01JDX4M1...",
"agent_id": "01JDX5ZQ8W3J2K6M9N4P7R1S0T",
"status": "completed",
"output": "Your order shipped on Tuesday and arrives Friday.",
"error": null,
"capped_reason": null,
"usage": { "credits": 1.25 },
"created_at": "2026-11-15T10:00:00.000Z",
"finished_at": "2026-11-15T10:00:09.000Z"
}| Field | Description |
|---|---|
status | queued, running, completed, failed, cancelled, or capped |
output | The Agent's final reply. null while the run is going, or when it wrote none |
error | { "code": "...", "message": "..." } when the run failed. The codes are out_of_credits and run_failed |
capped_reason | Which run limit stopped a capped run: steps, time, credits, or output. See Costs and limits |
usage | { "credits": 1.25 }, what the run spent. null while it runs |
finished_at | When the run ended, or null |
error.message is written for developers. Do not show it to your users.
The Message object
{
"id": "01JDY0B7...",
"thread_id": "01JDX4M1...",
"run_id": "01JDX4M2...",
"role": "assistant",
"parts": [
{
"type": "tool_call",
"id": "call_...",
"name": "lookup_order",
"kind": "app",
"status": "succeeded",
"summary": "Ran lookup order"
},
{ "type": "text", "text": "Your order shipped on Tuesday." }
],
"created_at": "2026-11-15T10:00:08.000Z"
}roleisuserorassistant- A part's
typeistextortool_call. More types may be added, so skip the ones you don't know - A tool call's
kindishercules(a tool that runs inside Hercules, like an integration),app(one of your app tools), orpage(a page action) - Its
statusissucceededorfailed, orsentfor a page action that went to the page. A page action whose arguments did not match its schema isfailed - Its
summaryis one generic line to show in place of the details, made from the tool's name: "Ran lookup order", "Couldn't run lookup order", or "Sent open order to the page". It never describes the arguments or the result - A message never carries a tool's arguments or result. An app tool's result is on its
tool_call.completedevent, and the arguments and results ofherculestools never leave Hercules
Limits
| Limit | Value | When it is reached |
|---|---|---|
| Request body | 8 MiB | 413 request_too_large |
Input text plus context | 262,144 characters | 400 message_too_long |
| Runs at once on one thread | 1 | 409 thread_busy |
| Runs per end user per hour | 20, set with Runs per user | 429 end_user_rate_limited |
| Credits per Agent per 24 hours, on apps | No limit, set with Daily spend limit | 429 agent_daily_limit_reached |
| Runs per Organization per minute | 60 | 429 rate_limited |
| Live streams of one run at once | 10 | 429 rate_limited |
wait_seconds | 60 | 400 invalid_request |
limit on events and messages | 100 | 400 invalid_request |
An app tool's result on an event | 32,000 characters of JSON, then a preview | Not an error |
- Every 429 carries a
Retry-Afterheader, in seconds. So does the 409thread_busyof a delete - Hercules also limits how fast one credential calls the API, counting each key and each run token by itself. Past it, the answer is a 429
rate_limitedwithRetry-After - Runs per user applies to runs with an
end_user. Daily spend limit applies to every run an app key starts. Neither applies to an Organization API key - The settings are under App access. See Agents in your app
Errors
Errors are RFC 9457 problem details, sent as application/problem+json:
{
"type": "about:blank",
"title": "Conflict",
"status": 409,
"detail": "...",
"message": "...",
"code": "thread_busy"
}Match on code, which stays the same within a version. detail is written for people and can change.
| Status | Code | What it means |
|---|---|---|
| 400 | invalid_request | A field, parameter, or header is wrong: an end_user sent with an Organization API key, a page action the Agent does not declare, a Last-Event-ID or after that is not a seq |
| 400 | invalid_api_version | Hercules-Version is missing or unknown. It is checked before the credential |
| 400 | invalid_authorization | The Authorization header says Bearer with no token after it |
| 400 | unsupported_content | An input part is not text |
| 400 | message_too_long | The input text plus context is over 262,144 characters |
| 401 | credential_required | No credential was sent, or a run token was sent to a route that takes a key |
| 401 | invalid_api_key | The key is wrong or revoked |
| 401 | invalid_run_token | On the events route: the run token is wrong, expired, revoked, for another run, or sent for JSON |
| 401 | invalid_workload_token | The bearer is a token signed by a Convex deployment, and Hercules could not verify it. Send your app key |
| 402 | out_of_credits | Your Organization has no AI credits left |
| 403 | missing_scope | The key does not have the agents:run scope |
| 403 | agent_not_exposed | Let apps run this agent is off for the Agent |
| 403 | organization_suspended | Your Organization is suspended |
| 404 | not_found | There is no such Agent, run, or thread, or it belongs to someone else. Also every route's answer while the Agents API is not on for your Organization, which is final |
| 409 | thread_busy | Starting a run: the thread already has a run going. Deleting a thread: its run is still stopping, and nothing was deleted. Send the delete again after Retry-After |
| 409 | run_id_conflict | The run_id was already used with a different request |
| 409 | agent_disabled | The Agent is turned off (Manage → Agent settings → Status) |
| 409 | agent_has_no_owner | The Agent has no owner to run as: the teammate who created it is gone |
| 409 | hercules_auth_required | Starting a run with an app key: the app does not use Hercules Auth 2.0, so Hercules cannot deliver the run's events to it or call its tools. Nothing was started. Upgrade the app, then send the request again |
| 413 | request_too_large | The request body is over 8 MiB |
| 429 | rate_limited | Starting a run: your Organization started more than 60 runs in a minute. Streaming: the run already has 10 live streams open. Any route: one credential called the API too fast. Wait for Retry-After |
| 429 | end_user_rate_limited | The end user reached Runs per user |
| 429 | agent_daily_limit_reached | The Agent reached its Daily spend limit |
| 500 | internal_error | Something failed in Hercules. instance holds an id to give support. Retry with backoff |
| 503 | service_unavailable | Hercules could not answer just now, or cannot tell yet whether the Agents API is on for your Organization (Retry-After: 5). Nothing was done, unless details.run_id and details.thread_id name a run you started: that run stays queued. Send the same request again, with the same run_id |