AgentOps MonitorStart free

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())

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.

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.

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

FieldTypeDefault when omittedNotes
external_idstring, 1 to 120 charactersrequiredYour identifier for the run. Re-posting it replaces the stored run; see Re-posting a run below.
agent_namestring, 1 to 120 charactersrequiredGroups runs of one agent in the dashboard.
statusrunning, completed, or failedcompleted
started_attimestampthe time the run is receivedOn a re-post, an omitted started_at keeps the stored value.
ended_attimestamp or nullnoneOn a re-post, an omitted ended_at keeps the stored value.
duration_msinteger 0 to 2,147,483,647, or nullnoneOn a re-post, an omitted duration_ms keeps the stored value.
tokens_in / tokens_outinteger 0 to 1,000,000,000,000sum 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_usdnumber 0 to 99,999,999.9999sum of the spans (0 with no spans)Same summing rule as the token totals; an explicit 0 is preserved. Stored with four decimal places.
metadataJSON object{}Up to 64 KB.
spansarray of span objects[]Up to 1,000 spans.

Span fields

FieldTypeDefault when omittedNotes
span_typellm, tool, or workflowrequired
iduuidgeneratedSend your own to keep stable span ids across re-posts.
parent_iduuid or nullnoneNests this span under another span of the same run; the run page renders the tree.
providerstring up to 64 characters, or nullnoneFor example openai.
modelstring up to 120 characters, or nullnoneFor example gpt-4o.
tool_namestring up to 160 characters, or nullnoneFor example stripe.refunds.create.
statusok, error, held, blocked, or retriedokRecorded as sent. held and blocked are states your agent reports; AgentOps Monitor does not hold or block calls.
started_attimestampthe time the span is received
duration_msinteger 0 to 2,147,483,647, or nullnone
tokens_in / tokens_outinteger 0 to 1,000,000,000,0000
cost_usdnumber 0 to 99,999,999.99990Stored with four decimal places.
input / outputJSON object{}Shown on the run page, with the full payload in the JSON export.
errorJSON object or nullnoneSurfaced on the span when it fails.
metadataJSON 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.