Docs
Generate a key. Post a trace. See the run.
Ingestion is a plain HTTPS endpoint. There is no AgentOps package to install and no agent to run.
1. Generate an API key
Create an account, then go to API keys to mint one. Keys start with aom_live_. The full key value is shown only at creation and never again.
2. Post a trace
Send your run as JSON to POST /api/ingest with your key in the Authorization header. Pick your language; every tab sends the same run (the Python tab uses the third-party requests library, Node.js 18+ has fetch built in):
import requests
response = requests.post(
"https://agentopsmonitor.com/api/ingest",
headers={"Authorization": "Bearer aom_live_..."},
json={
"external_id": "run-001",
"agent_name": "refund-triage",
"status": "completed",
"spans": [
{"span_type": "llm", "provider": "openai", "model": "gpt-4o",
"tool_name": "openai.chat", "tokens_in": 8204, "tokens_out": 512,
"cost_usd": 0.08, "duration_ms": 600},
],
},
)
print(response.status_code, response.json())const response = await fetch("https://agentopsmonitor.com/api/ingest", {
method: "POST",
headers: {
Authorization: "Bearer aom_live_...",
"Content-Type": "application/json",
},
body: JSON.stringify({
external_id: "run-001",
agent_name: "refund-triage",
status: "completed",
spans: [
{ span_type: "llm", provider: "openai", model: "gpt-4o",
tool_name: "openai.chat", tokens_in: 8204, tokens_out: 512,
cost_usd: 0.08, duration_ms: 600 },
],
}),
});
console.log(response.status, await response.json());curl -X POST https://agentopsmonitor.com/api/ingest \
-H "Authorization: Bearer aom_live_..." \
-H "Content-Type: application/json" \
-d '{"external_id":"run-001","agent_name":"refund-triage","status":"completed","spans":[{"span_type":"llm","provider":"openai","model":"gpt-4o","tool_name":"openai.chat","tokens_in":8204,"tokens_out":512,"cost_usd":0.08,"duration_ms":600}]}'The same call works with curl or any HTTP client. With Python's urllib, set your own User-Agent header: requests that carry urllib's default one are refused with HTTP 403 and the text error code: 1010. A 200 response returns the stored run_id, span_count, and run_url, the link straight to that run's trace, so an agent or a pager message can carry it. Run-level tokens_in, tokens_out, and cost_usd are optional: omit them and the run totals are summed from its spans; send them and your values are stored as sent.
3. Handle errors
Missing or invalid key: 401. Malformed JSON or schema violations: 400. Body over 1 MB: 413. Rate limit exceeded: 429. Free-tier monthly run limit reached: 402 with quota_exceeded, and the response includes runs_used and runs_included. Paid tiers are not capped and no overage is charged.
A 429 carries a Retry-After header with the seconds left in the current minute and repeats it as retry_after_seconds in the body: wait that long, then retry. Every response carries an X-Request-Id header, and every error body repeats it as request_id. Quote it when you contact support and we can find the request in our logs. Send your own X-Request-Id (8 to 64 letters, digits, dots, underscores, or hyphens) and it is echoed back.
Pick the status you got to see the exact body and what to do about it.
The run and its spans were stored.
{
"ok": true,
"run_id": "5f0c6f2e-8a1b-4c3d-9e7f-1a2b3c4d5e6f",
"span_count": 3,
"run_url": "https://agentopsmonitor.com/app/runs/5f0c6f2e-8a1b-4c3d-9e7f-1a2b3c4d5e6f"
}What to do
- Open run_url to land on the trace, or open the dashboard and the run is at the top of Recent runs.
- Posting the same external_id again replaces that run and its spans, so you can send a run while it is running and again when it ends.
invalid_json The body did not parse as JSON.
{
"error": {
"message": "Request body is not valid JSON.",
"code": "invalid_json"
},
"request_id": "req_2a9f4c1e7b3d"
}invalid_payload The JSON parsed but does not match the run format.
{
"error": {
"message": "Invalid request payload.",
"code": "invalid_payload"
},
"request_id": "req_2a9f4c1e7b3d"
}What to do
- Serialize the body with your JSON library rather than building the string by hand.
- Every run needs external_id and agent_name (1 to 120 characters each). Every span needs span_type: llm, tool, or workflow.
- Timestamps are ISO 8601 in UTC ending in Z. input and output must be JSON objects, not strings. At most 1,000 spans per request.
missing_bearer No Authorization header, or it is not in the form Bearer <key>.
{
"error": {
"message": "Missing or invalid Authorization header.",
"code": "missing_bearer"
},
"request_id": "req_2a9f4c1e7b3d"
}invalid_api_key The key is not one we issued, or it was revoked.
{
"error": {
"message": "Unknown or disabled API key.",
"code": "invalid_api_key"
},
"request_id": "req_2a9f4c1e7b3d"
}What to do
- Send the header as Authorization: Bearer aom_live_... with your full key.
- The full key is shown only once, at creation. If you no longer have it, create a new key on the API keys page and revoke the old one.
quota_exceeded A Free account has used its 10,000 runs this calendar month.
{
"error": {
"message": "Monthly run limit reached (10000 of 10000 runs). Upgrade your plan to keep ingesting.",
"code": "quota_exceeded"
},
"request_id": "req_2a9f4c1e7b3d",
"runs_used": 10000,
"runs_included": 10000
}What to do
- Only new runs count. Posting again with the external_id of a run you already sent is still accepted.
- New runs are accepted again from the first of next month. Team accounts are not capped.
payload_too_large The request body is over 1 MB.
{
"error": {
"message": "Request body exceeds the size limit.",
"code": "payload_too_large"
},
"request_id": "req_2a9f4c1e7b3d"
}payload_too_large One span's input, output, error, and metadata together are over 64 KB.
{
"error": {
"message": "Span payload exceeds the size limit.",
"code": "payload_too_large"
},
"request_id": "req_2a9f4c1e7b3d"
}payload_too_large The run's metadata is over 64 KB.
{
"error": {
"message": "Run metadata exceeds the size limit.",
"code": "payload_too_large"
},
"request_id": "req_2a9f4c1e7b3d"
}What to do
- Trim what you put in input and output: keep the prompt and response summaries you will want at 2 a.m., not whole documents.
- The message says which limit you hit.
rate_limited This key sent more requests in the current minute than the ingest limit allows.
Response headers Retry-After: 17
{
"error": {
"message": "Ingest rate limit exceeded.",
"code": "rate_limited"
},
"request_id": "req_2a9f4c1e7b3d",
"retry_after_seconds": 17
}What to do
- The count is per key and resets at the start of each minute. Wait the Retry-After seconds (also retry_after_seconds in the body), then retry.
- Send one request per run with all its spans rather than one request per span.
Request limits
Up to 1,000 spans per request (400 above that). 64 KB per span across input, output, error, and metadata, and 64 KB of run metadata (413 above either). input and output must be JSON objects. Timestamps must be ISO 8601 in UTC ending in Z, for example 2026-10-11T02:14:11Z.
Field reference
Every field the endpoint accepts, with the default applied when you omit it. The defaults and bounds below are the schema the route validates against. Invalid values return 400; exceeding either 64 KB size cap returns 413.
Run fields
| Field | Type | Default when omitted | Notes |
|---|---|---|---|
external_id | string, 1 to 120 characters | required | Your identifier for the run. Re-posting it replaces the stored run; see Re-posting a run below. |
agent_name | string, 1 to 120 characters | required | Groups runs of one agent in the dashboard. |
status | running, completed, or failed | completed | |
started_at | timestamp | the time the run is received | On a re-post, an omitted started_at keeps the stored value. |
ended_at | timestamp or null | none | On a re-post, an omitted ended_at keeps the stored value. |
duration_ms | integer 0 to 2,147,483,647, or null | none | On a re-post, an omitted duration_ms keeps the stored value. |
tokens_in / tokens_out | integer 0 to 1,000,000,000,000 | sum of the spans (0 with no spans) | Omit one and it is stored as the sum over the run's spans; send it, even 0, and your value is stored as sent. |
cost_usd | number 0 to 99,999,999.9999 | sum of the spans (0 with no spans) | Same summing rule as the token totals; an explicit 0 is preserved. Stored with four decimal places. |
metadata | JSON object | {} | Up to 64 KB. |
spans | array of span objects | [] | Up to 1,000 spans. |
Span fields
| Field | Type | Default when omitted | Notes |
|---|---|---|---|
span_type | llm, tool, or workflow | required | |
id | uuid | generated | Send your own to keep stable span ids across re-posts. |
parent_id | uuid or null | none | Nests this span under another span of the same run; the run page renders the tree. |
provider | string up to 64 characters, or null | none | For example openai. |
model | string up to 120 characters, or null | none | For example gpt-4o. |
tool_name | string up to 160 characters, or null | none | For example stripe.refunds.create. |
status | ok, error, held, blocked, or retried | ok | Recorded as sent. held and blocked are states your agent reports; AgentOps Monitor does not hold or block calls. |
started_at | timestamp | the time the span is received | |
duration_ms | integer 0 to 2,147,483,647, or null | none | |
tokens_in / tokens_out | integer 0 to 1,000,000,000,000 | 0 | |
cost_usd | number 0 to 99,999,999.9999 | 0 | Stored with four decimal places. |
input / output | JSON object | {} | Shown on the run page, with the full payload in the JSON export. |
error | JSON object or null | none | Surfaced on the span when it fails. |
metadata | JSON object | {} | input, output, error, and metadata together are capped at 64 KB per span. |
Re-posting a run
Re-posting a run with an external_id your account has used before updates the stored run instead of creating a second one, and replaces its spans wholesale: the previously stored spans are deleted and the posted spans are inserted. Omitted started_at, ended_at, and duration_ms keep their stored values; every other run field is replaced by the posted value, its default from the table above, or the re-summed span totals. The response returns the same run_id, and the re-posted run is counted once for usage, not twice.
View in the dashboard
Open the dashboard to see recent runs and their cost. Click any run to inspect its spans.
Spend caps: not available yet
Not available yet. Today AgentOps Monitor records the cost and token counts your agent reports at ingest and shows them on every run in the dashboard. A runaway call is recorded with the rest of the run. It is not stopped, and the product does not halt a run or refuse a spend. Spend caps and automated budget enforcement are on the roadmap - see features.