---
title: "Agents API"
description: "Run a Hercules Agent from your app's backend with the Agents API. Start runs with a key, stream replies to the browser, and get each run's results in your app."
image: "https://hercules.app/og/home"
---

# Agents API

> Run a Hercules Agent from your app's backend with the Agents API. Start runs with a key, stream replies to the browser, and get each run's results in your app.

> **Note:** The Agents API and the `@usehercules/agents` package are in beta, so things may change. They are
> switched on one Organization at a time, and every route answers 404 `not_found` until they are on
> for yours. To try them, contact [hello@hercules.app](mailto:hello@hercules.app).

Run a Hercules Agent from your app with the Agents API. Your app's backend starts each run with a key, the browser streams the reply with a token that reads only that run, and Hercules delivers the run's results into your app.

- Keys stay on your server. The browser gets a read-only token for one run
- Your app's database gets every message, tool call, and page action, even when no one has the page open
- In a Convex app, `@usehercules/agents` does all of this for you. See [Convex backend](https://hercules.app/docs/agents/convex-backend)

### How does a run work?

**Your backend starts the run**

It calls `POST /v1/agents/{agent_id}/runs` with your app's key, and names the signed-in user the
run is for. The answer holds the run, and a `live` URL and token for it.

**The browser streams the reply**

It reads the run's events from `live.url` with `live.token`, so the reply appears as the Agent
writes it.

**Hercules delivers the results to your app**

It posts each durable event (messages, tool calls, page actions, and the run's end) to your
app's events endpoint, signed by your app's Hercules Auth. See [Event
delivery](https://hercules.app/docs/agents/event-delivery).

**The run ends**

Every run ends with exactly one of `run.completed`, `run.failed`, `run.cancelled`, or
`run.capped`.

### Which credential do I use?

Send it as `Authorization: Bearer <credential>`.

| Credential               | Where it comes from                                                    | Works on                                    |
| ------------------------ | ---------------------------------------------------------------------- | ------------------------------------------- |
| **App key**              | `HERCULES_API_KEY`, already set in every Convex deployment of your app | Every route                                 |
| **Organization API key** | **Settings** → **API keys**                                            | Every route, as your Organization           |
| **Run token**            | `live.token`, returned when the run starts                             | That run's events, as a stream, and no more |

- Never send a key to the browser. Only the events route answers calls from a page on another domain
- Keys need the `agents:run` scope. App keys and Organization API keys have it
- An app key reaches only the runs and threads its app started. An Organization API key reaches every run and thread of your Organization's Agents
- The Agent must have **Let apps run this agent** on (**Manage** → **Agent settings** → **App access**), or starting a run answers 403 `agent_not_exposed`

The Agent's id is a ULID in uppercase with no prefix, such as `01JDX5ZQ8W3J2K6M9N4P7R1S0T`. It is the last part of the Agent's address in the console: `https://hercules.app/org/<org-slug>/agents/<agent-id>`.

### What can a run token do?

A run token starts with `hrt_` and is safe to hand to a browser:

- It reads one run's events as a stream (`Accept: text/event-stream`), until 1 hour after the run ends. Sent for JSON, it is refused with 401 `invalid_run_token`, and on every other route with 401 `credential_required`
- It is stable. Start the run again with the same `run_id` and the same request, and you get the same run and the same `live.token`
- It can be used many times, but a run takes 10 streams at once. One more is a 429 `rate_limited`
- Its stream hides tool details unless the run set `expose_tool_details`. See [What does a run token see of tools?](https://hercules.app/docs/agents/run-events#what-does-a-run-token-see-of-tools)
- Deleting the run's thread ends its stream and revokes the token

### How does versioning work?

Send the `Hercules-Version` header on every request, the stream included. The current version is `2025-12-09`.

- A missing or unknown version is a 400 with the code `invalid_api_version`. The version is checked before the credential, so this is the answer whatever key or token came with it
- A run keeps the version it started with. Its events, deliveries, and live stream all use that version
- Within a version, changes only add things: fields, event types, message part types, and error codes. Ignore the ones you don't know

### How do I start a run?

```bash Start a run
curl "https://api.hercules.app/v1/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $HERCULES_API_KEY" \
  -H "Hercules-Version: 2025-12-09" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user": { "token_identifier": "<issuer>|<subject>" },
    "input": [{ "type": "text", "text": "Where is my order?" }]
  }'
```

```json 202 Accepted
{
  "run": {
    "id": "01JDX4M2...",
    "thread_id": "01JDX4M1...",
    "agent_id": "01JDX5ZQ8W3J2K6M9N4P7R1S0T",
    "status": "queued",
    "output": null,
    "error": null,
    "capped_reason": null,
    "usage": null,
    "created_at": "2026-11-15T10:00:00.000Z",
    "finished_at": null
  },
  "live": {
    "url": "https://api.hercules.app/v1/agents/runs/01JDX4M2.../events",
    "token": "hrt_..."
  }
}
```

- `end_user.token_identifier` is the signed-in user, as Convex names them: the `tokenIdentifier` from `ctx.auth.getUserIdentity()`. Leave `end_user` out for your app's own job, such as a scheduled function
- Leave out `thread_id` to open a new thread, or pass one to continue it
- Send your own `run_id` (a UUID, or a ULID in uppercase), so a retried request returns the same run instead of starting another. A UUID sent in uppercase comes back in lowercase
- Set `wait_seconds` (up to 60) to wait for short runs. A run that finishes in time answers `200` with its output

Every field is in the [Agents API reference](https://hercules.app/docs/agents/api-reference#start-a-run).

### How do I stream the reply?

```bash Stream a run's events
curl -N "https://api.hercules.app/v1/agents/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $RUN_TOKEN" \
  -H "Hercules-Version: 2025-12-09" \
  -H "Accept: text/event-stream"
```

```text One server-sent event
id: 3
data: {"id":"01JDX4M2...:3","seq":3,"run_id":"01JDX4M2...","thread_id":"01JDX4M1...","type":"message.delta","created_at":"2026-11-15T10:00:01.000Z","data":{"message_id":"01JDX4N0...","text":"Your order "}}
```

- Each event's `id` is its `seq`
- The stream closes after the run's final event, and after 10 minutes at most. If it closes or drops before a final event, reconnect with the `Last-Event-ID` header set to the last `id` you got. A `Last-Event-ID` that is not a seq (a whole number from 0 to 2147483647) is a 400 `invalid_request`
- A `: keep-alive` comment line arrives every 15 seconds. Server-sent event parsers skip it
- In a browser, read the stream with `fetch`, not `EventSource`: the route needs the `Authorization` and `Hercules-Version` headers, which `EventSource` cannot send
- A run takes 10 streams at once. One more is a 429 `rate_limited` with `Retry-After: 5`, so check the status before you read the body

See [Run events](https://hercules.app/docs/agents/run-events#how-do-i-stream-a-run).

### What do requests and lists look like?

- Bodies are JSON with `snake_case` fields, up to 8 MiB. Timestamps are UTC, in ISO 8601
- Errors are problem details (`application/problem+json`) with a stable `code`. See [Errors](https://hercules.app/docs/agents/api-reference#errors)
- A 503 `service_unavailable` means try again: wait for its `Retry-After` when it has one, and send the same request. A 500 `internal_error` is also on Hercules's side. Retry it with backoff
- Always retry a 503 from `POST /v1/agents/{agent_id}/runs` with the same `run_id`. The run may have been created without Hercules being able to confirm that it started. It then stays queued, and the answer names it and its thread in `details.run_id` and `details.thread_id`. The same request with both starts the run or returns it started, and charges nothing more. Sent again without the `run_id`, it would start a second run
- Hercules also limits how fast one credential calls the API. Each key and each run token is counted by itself, so another app's traffic never uses up yours. Past the limit the answer is a 429 `rate_limited` with `Retry-After`
- A thread's messages answer `{ "data": [...], "has_more": true }`, newest first. Page them with `limit` (1 to 100, default 100), `starting_after` (a message id, for older messages), and `ending_before` (a message id, for newer ones)
- A run's events answer the same shape, oldest first, paged with `after` (an event's `seq`)
- No route lists threads or runs. Store the id of each thread you want to open again

### What can an Organization API key do?

An Organization API key runs an Agent as your Organization, from any server. Use it for a backend that is not a Hercules app:

- It starts runs on every Agent of your Organization that has **Let apps run this agent** on, and reads, streams, and cancels those runs, and reads and deletes their threads
- Deleting a thread whose run is still stopping answers 409 `thread_busy` with `Retry-After`, and deletes nothing. Send the delete again. See [Delete a thread](https://hercules.app/docs/agents/api-reference#delete-a-thread)
- Its runs act for no end user. Sending `end_user` is a 400 `invalid_request`, so its threads belong to your Organization, and your server decides who may see each
- Nothing is delivered. Read a run with `GET /v1/agents/runs/{run_id}`, its events with `GET /v1/agents/runs/{run_id}/events`, and a thread with `GET /v1/agents/threads/{thread_id}/messages`
- **Runs per user** and **Daily spend limit** do not apply to it. Your Organization's rate of 60 runs a minute and its credit balance do

### Additional FAQ

#### Can a page call the API from the browser?

Only to stream a run's events with its run token. Start runs, read threads, and cancel runs from
your server, where the key stays secret. In a Convex app, the page calls your own Convex
functions, and they call Hercules.

#### Where does Hercules deliver a run's events?

To the Convex deployment whose app key started the run, at
`https://<deployment>.convex.site/hercules/agents/events`. Your app needs Hercules Auth for this.
A run started with an Organization API key has no app to deliver to, so read its events and
messages from the API. See [Event delivery](https://hercules.app/docs/agents/event-delivery).

#### What if a run gets stuck?

It is ended for you. A run whose execution is lost ends as `failed`, with the error code
`run_failed`, within a few minutes. So every run reaches a final event, and its thread is free for
the next run.

#### Why does every route answer 404?

The Agents API is not on for your Organization yet. Until it is, every route answers 404
`not_found`, the same as for an Agent, run, or thread that does not exist. That answer is final,
so do not retry it. In an app built with `@usehercules/agents`, each run then fails with the code
`agent_not_found`. Contact [hello@hercules.app](mailto:hello@hercules.app).

While Hercules cannot tell yet whether the API is on for your Organization, it answers 503
`service_unavailable` with `Retry-After: 5` instead. Nothing was done: send the request again.

#### Who pays for a run?

Your Organization, in AI credits, the same as every other Agent run. A finished run's
`usage.credits` says what it cost. See [Costs and limits](https://hercules.app/docs/agents/costs-and-limits).

Previous: [Agent costs and run limits](https://hercules.app/docs/agents/costs-and-limits)

Next: [Run Agents from your Convex backend](https://hercules.app/docs/agents/convex-backend)

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#webpage",
      "url": "https://hercules.app/docs/agents/api",
      "name": "Agents API",
      "description": "Run a Hercules Agent from your app's backend with the Agents API. Start runs with a key, stream replies to the browser, and get each run's results in your app.",
      "dateModified": "2026-11-16T21:16:56.000Z",
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "breadcrumb": {
        "@id": "https://hercules.app/docs/agents/api#breadcrumb"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://hercules.app/docs/agents/api#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Hercules",
          "item": "https://hercules.app/docs"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Agents API",
          "item": "https://hercules.app/docs/agents/api"
        }
      ]
    },
    {
      "@type": [
        "Article",
        "TechArticle"
      ],
      "@id": "https://hercules.app/docs/agents/api#article",
      "headline": "Agents API",
      "name": "Agents API",
      "description": "Run a Hercules Agent from your app's backend with the Agents API. Start runs with a key, stream replies to the browser, and get each run's results in your app.",
      "url": "https://hercules.app/docs/agents/api",
      "mainEntityOfPage": {
        "@id": "https://hercules.app/docs/agents/api#webpage"
      },
      "image": "https://hercules.app/og/home",
      "dateModified": "2026-11-16T21:16:56.000Z",
      "keywords": "agents api, agent runs api, HERCULES_API_KEY, run token, Hercules-Version, stream agent reply, server-sent events",
      "publisher": {
        "@id": "https://hercules.app/#organization"
      },
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "inLanguage": "en-US"
    }
  ]
}
```
