Hercules

DevelopersAPI reference

Developers

Agents API reference

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.

MethodPathWhat it does
POST/v1/agents/{agent_id}/runsStart a run on a new or existing thread
GET/v1/agents/runs/{run_id}Read a run
GET/v1/agents/runs/{run_id}/eventsReplay or stream a run's events
POST/v1/agents/runs/{run_id}/cancelStop a run
GET/v1/agents/threads/{thread_id}/messagesRead 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_id is a ULID in uppercase. A run_id or thread_id you 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 400 invalid_request

Start a run

POST /v1/agents/{agent_id}/runs

FieldTypeRequiredDescription
run_idstringNoA UUID or ULID. It is also the idempotency key. Hercules makes one when you leave it out
thread_idstringNoLeave it out to open a new thread. A new UUID or ULID opens a thread under that id
end_userobjectNoThe 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
inputarrayYesContent parts. Only { "type": "text", "text": "..." } for now. Anything else is a 400 unsupported_content
contextobjectNoNamed JSON values about the page, added to the input. They count toward the size limit
page_actionsstring[]NoThe 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_detailsbooleanNoDefault 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_secondsintegerNo0 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_id with the same request returns the run it started, with the same live.token, and starts nothing. A different wait_seconds is still the same request. The same run_id with a different request is a 409 run_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/agents retires the id for you, and refuses it with thread_deleted
  • Do not send a run_id again 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 new live.token, on a new thread unless it names one
  • token_identifier is <issuer>|<subject>, the user's tokenIdentifier in 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_user is a 400 invalid_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_unavailable with details.run_id and details.thread_id means the run was created, but Hercules could not confirm that it started. It stays queued. Send the same request again with that run_id and thread_id after Retry-After (2 seconds): it starts the run or returns it started, and charges nothing more. The run_id alone is enough, but without it the retry starts a second run. So always retry a 503 here with the same run_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

QueryDescription
afterAn event's seq, 0 to 2147483647. Default 0, the start of the run
limit1 to 100, default 100. JSON only
AcceptCredentialAnswer
application/jsonApp key or Organization API key{ "data": Event[], "has_more": false }: the durable events after after, oldest first
text/event-streamAny, including the run's tokenEvery event after after or Last-Event-ID, live, until the run's final event
  • A run token sent for application/json is a 401 invalid_run_token
  • On a stream, the Last-Event-ID header wins over after. Either one that is not a whole number from 0 to 2147483647 is a 400 invalid_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_limited with Retry-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 user message when it starts, and the reply it finished with as an assistant message when it ends. A run that is still queued has no message here yet, and one that is still going has no reply
  • A user message holds the input text, without the context sent 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_busy with a Retry-After header, 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_id of 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"
}
FieldDescription
statusqueued, running, completed, failed, cancelled, or capped
outputThe 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_reasonWhich 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_atWhen 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"
}
  • role is user or assistant
  • A part's type is text or tool_call. More types may be added, so skip the ones you don't know
  • A tool call's kind is hercules (a tool that runs inside Hercules, like an integration), app (one of your app tools), or page (a page action)
  • Its status is succeeded or failed, or sent for a page action that went to the page. A page action whose arguments did not match its schema is failed
  • Its summary is 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.completed event, and the arguments and results of hercules tools never leave Hercules

Limits

LimitValueWhen it is reached
Request body8 MiB413 request_too_large
Input text plus context262,144 characters400 message_too_long
Runs at once on one thread1409 thread_busy
Runs per end user per hour20, set with Runs per user429 end_user_rate_limited
Credits per Agent per 24 hours, on appsNo limit, set with Daily spend limit429 agent_daily_limit_reached
Runs per Organization per minute60429 rate_limited
Live streams of one run at once10429 rate_limited
wait_seconds60400 invalid_request
limit on events and messages100400 invalid_request
An app tool's result on an event32,000 characters of JSON, then a previewNot an error
  • Every 429 carries a Retry-After header, in seconds. So does the 409 thread_busy of 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_limited with Retry-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.

StatusCodeWhat it means
400invalid_requestA 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
400invalid_api_versionHercules-Version is missing or unknown. It is checked before the credential
400invalid_authorizationThe Authorization header says Bearer with no token after it
400unsupported_contentAn input part is not text
400message_too_longThe input text plus context is over 262,144 characters
401credential_requiredNo credential was sent, or a run token was sent to a route that takes a key
401invalid_api_keyThe key is wrong or revoked
401invalid_run_tokenOn the events route: the run token is wrong, expired, revoked, for another run, or sent for JSON
401invalid_workload_tokenThe bearer is a token signed by a Convex deployment, and Hercules could not verify it. Send your app key
402out_of_creditsYour Organization has no AI credits left
403missing_scopeThe key does not have the agents:run scope
403agent_not_exposedLet apps run this agent is off for the Agent
403organization_suspendedYour Organization is suspended
404not_foundThere 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
409thread_busyStarting 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
409run_id_conflictThe run_id was already used with a different request
409agent_disabledThe Agent is turned off (Manage → Agent settings → Status)
409agent_has_no_ownerThe Agent has no owner to run as: the teammate who created it is gone
409hercules_auth_requiredStarting 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
413request_too_largeThe request body is over 8 MiB
429rate_limitedStarting 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
429end_user_rate_limitedThe end user reached Runs per user
429agent_daily_limit_reachedThe Agent reached its Daily spend limit
500internal_errorSomething failed in Hercules. instance holds an id to give support. Retry with backoff
503service_unavailableHercules 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