See what your agent actually called.

01 / Why

An agent that stopped, and no way to see where.

When an agent run goes wrong, the question is almost always the same one: what did it call, in what order, and what did it get back? A log of your own code answers half of that. It does not tell you that the fourteenth call asked for a filter we do not serve, or that the run went over its rate limit at request 412 and everything after that is a 403 rather than a result.

The flight recorder answers it from our side. Every request the key made while recording was on, in order, with the status, how long it took, how big the response was, and which of five things happened: we served it, we do not cover that endpoint, we do not cover that filter, you asked us to simulate a fault, or you were over the limit.

02 / Turning it on

One switch, on the key, for 24 hours.

Open your dashboard and press Record in the Recording column beside the key you are about to use. That is the whole setup — no flag in your client, no change to your code, no separate endpoint.

Recording lasts 24 hours and then stops by itself. Pressing Record again while it is on gives it another 24 hours from that moment, and Stop ends it immediately. The deadline exists so that a switch nobody remembered to turn off does not keep writing forever.

03 / Runs

Name your run, or let us group it.

A trace is grouped into runs. If you send a header called X-SandboxAPIs-Run with a name of your choosing, every request carrying that name is one run — which is what you want when a nightly job and a local experiment are both using the same key. The name may be up to 64 characters of letters, digits and . _ - :; anything else is ignored, and the request is still recorded.

# curl
curl -H "Authorization: Bearer $SANDBOXAPIS_API_KEY" \
     -H "X-SandboxAPIs-Run: nightly-eval" \
     https://gh.sandboxapis.dev/repos/olympus-labs/parthenon/pulls

# Octokit
const octokit = new Octokit({
  auth: process.env.SANDBOXAPIS_API_KEY,
  baseUrl: "https://gh.sandboxapis.dev",
  request: { headers: { "x-sandboxapis-run": "nightly-eval" } },
});

The header changes nothing about the response. It is read and never passed on, so a run name cannot affect what you are served — which means you can leave it in place permanently and it costs nothing when recording is off.

Requests with no run name are grouped by when they happened: a gap of more than five minutes starts a new run. Both kinds appear in the same list.

The eval harnesses on the answer-key eval pack read SANDBOXAPIS_RUN from your environment and send it as this header, so a failing eval can be opened as its own trace.

04 / Reading a trace

A line per request, and a download.

Each run opens as a list, newest first: the time to the millisecond, the method, the path with its query string, the status, the time it took and the size of the response. Select a row to see the rest — which snapshot answered it, the provider's own request id, the content type, and whether it was a fault you asked us to simulate.

The chips above the list narrow it to the requests that went wrong: the ones we do not cover, the writes we refused, the faults you simulated, and the errors. Download JSON gives you the rows as we hold them. Download HAR gives you a HAR 1.2 file, which any browser's network panel and most HTTP tools will open directly.

05 / What is stored

Enough to debug, and nothing more.

A recorded request holds the time, the host and provider, the snapshot that answered it, the method, the path, the query string, the status, how long it took, the response size, the content type, and the provider's own request id.

It does not hold a request body, a response body, any request header — including the one you authenticated with — any other response header, a cookie, an IP address or a User-Agent.

The query string is kept, because without it a trace cannot tell a paging problem from a filter problem. The values of parameters named like a credential — anything called token, key, secret, password, sig or auth — are replaced with [redacted] before the row is written, and the whole string is cut off at 1,024 characters.

06 / Limits

Seven days, and 50,000 requests a day.

Rows are deleted 7 days after they are written. That covers "the nightly job broke on Tuesday" and keeps a trace from becoming a permanent record of your traffic.

One key records at most 50,000 requests per day, counted from midnight UTC. At that point recording stops and the page tells you when it stopped and that requests since then are missing. We deliberately do not thin the list out instead: a timeline with invisible gaps in it is worse than one that says where it ends, because you would believe it.

The recorder is available on every plan, including the free one. Download a trace if you want to keep it past 7 days — see our privacy page for exactly what a row holds and how long we keep it.