---
title: "Agents API reference"
description: "Every route of the Hercules Agents API: start, read, stream, and cancel runs, read and delete threads, plus Run and Message objects, limits, and error codes."
image: "https://hercules.app/og/home"
---

# Agents API reference

> Every route of the Hercules Agents API: start, read, stream, and cancel runs, read and delete threads, plus Run and Message objects, limits, and error codes.

> **Note:** The Agents API is in beta, so things may change. See [Agents API](https://hercules.app/docs/agents/api) for credentials and
> versioning.

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_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`

| 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](https://hercules.app/docs/agents/run-events#what-does-a-run-token-see-of-tools) |
| `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](#the-run-object), shortened here:

```json
{
  "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](https://hercules.app/docs/agents/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](https://hercules.app/docs/apps/users-auth/upgrade-to-hercules-auth-2). Hercules signs the run's [event deliveries](https://hercules.app/docs/agents/event-delivery) and its [app tool](https://hercules.app/docs/agents/app-tools) 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](#the-run-object). 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/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](https://hercules.app/docs/agents/run-events).

### Cancel a run

`POST /v1/agents/runs/{run_id}/cancel` stops the run and returns the [Run](#the-run-object). 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:

```json
{ "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](#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](https://hercules.app/docs/agents/convex-backend#what-happens-when-i-delete-a-thread).

### The Run object

```json
{
  "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](https://hercules.app/docs/agents/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

```json
{
  "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](https://hercules.app/docs/agents/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](https://hercules.app/docs/agents/run-events), and the arguments and results of `hercules` tools 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-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](https://hercules.app/docs/agents/agents-in-apps#how-do-i-limit-what-the-agent-spends)

### Errors

Errors are RFC 9457 problem details, sent as `application/problem+json`:

```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](https://hercules.app/docs/apps/users-auth/upgrade-to-hercules-auth-2), 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` |

Previous: [Give an Agent your app's tools](https://hercules.app/docs/agents/app-tools)

Next: [Agent run events](https://hercules.app/docs/agents/run-events)

Every docs page is listed in [llms.txt](https://hercules.app/docs/llms.txt).

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://hercules.app/#organization",
      "name": "Hercules",
      "url": "https://hercules.app",
      "logo": {
        "@type": "ImageObject",
        "url": "https://hercules.app/logo-128.png"
      }
    },
    {
      "@type": "WebSite",
      "@id": "https://hercules.app/docs#website",
      "name": "Hercules",
      "url": "https://hercules.app/docs",
      "publisher": {
        "@id": "https://hercules.app/#organization"
      }
    },
    {
      "@type": "WebPage",
      "@id": "https://hercules.app/docs/agents/api-reference#webpage",
      "url": "https://hercules.app/docs/agents/api-reference",
      "name": "Agents API reference",
      "description": "Every route of the Hercules Agents API: start, read, stream, and cancel runs, read and delete threads, plus Run and Message objects, limits, and error codes.",
      "dateModified": "2026-11-16T23:58:36.000Z",
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "breadcrumb": {
        "@id": "https://hercules.app/docs/agents/api-reference#breadcrumb"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://hercules.app/docs/agents/api-reference#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Hercules",
          "item": "https://hercules.app/docs"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Agents API reference",
          "item": "https://hercules.app/docs/agents/api-reference"
        }
      ]
    },
    {
      "@type": [
        "Article",
        "TechArticle"
      ],
      "@id": "https://hercules.app/docs/agents/api-reference#article",
      "headline": "Agents API reference",
      "name": "Agents API reference",
      "description": "Every route of the Hercules Agents API: start, read, stream, and cancel runs, read and delete threads, plus Run and Message objects, limits, and error codes.",
      "url": "https://hercules.app/docs/agents/api-reference",
      "mainEntityOfPage": {
        "@id": "https://hercules.app/docs/agents/api-reference#webpage"
      },
      "image": "https://hercules.app/og/home",
      "dateModified": "2026-11-16T23:58:36.000Z",
      "keywords": "agents api reference, start a run, cancel a run, thread messages, delete thread, run object, error codes, rate limits",
      "publisher": {
        "@id": "https://hercules.app/#organization"
      },
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "inLanguage": "en-US"
    }
  ]
}
```
