Retrieve run trace

Returns the OTel trace subtree for the requested run — the run’s span as rootSpan, its ancestor chain, and its descendant spans. For child or nested runs in a large trace, this is scoped to that run rather than the trace-wide root. Pass page[size] or page[after] to page the trace as flat spans instead; paging works for runs at the root of their trace.

GET /api/v1/runs/{runId}/trace

TypeScript

Trace tree

const response = await fetch("https://api.trigger.dev/api/v1/runs/run_1234/trace", { headers: { Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}`, }, }); const { trace } = await response.json();

200

{
  "trace": {
    "traceId": "<string>",
    "rootSpan": {
      "id": "<string>",
      "parentId": "<string>",
      "runId": "<string>",
      "data": {
        "message": "<string>",
        "taskSlug": "<string>",
        "startTime": "2023-11-07T05:31:56Z",
        "duration": 123,
        "isError": true,
        "isPartial": true,
        "isCancelled": true,
        "level": "TRACE",
        "attemptNumber": 123,
        "properties": {},
        "events": [
          {
            "name": "<string>",
            "time": "2023-11-07T05:31:56Z",
            "properties": {}
          }
        ]
      },
      "children": "<array>"
    }
  }
}

Returns the OpenTelemetry trace subtree for the run you request. The response trace.rootSpan is that run’s span — not necessarily the trace-wide root — with its descendant spans nested under children.

For a child or nested run inside a large trace, this endpoint scopes the tree to that run so you still get a useful subtree even when the full trace has more spans than the platform can return in one response.

For a finished run, spans that finish more than 7 days after the run are returned in their last recorded state.

Page large traces

The tree response stops at a size limit. To get every span of a large trace, page it: send page[size] (1,000–10,000) on the first request, then pass each response’s pagination.next back as page[after] until it’s absent.

Your backend code

const spans = [];
let after: string | undefined;

do {
  const query = new URLSearchParams({ "page[size]": "10000" });
  if (after) query.set("page[after]", after);

  const response = await fetch(`https://api.trigger.dev/api/v1/runs/run_1234/trace?${query}`, {
    headers: { Authorization: `Bearer ${process.env.TRIGGER_SECRET_KEY}` },
  });
  const page = await response.json();

  spans.push(...page.data);
  after = page.pagination.next;
} while (after);

• Paging works for runs at the root of their trace. Other runs return 400; request their trace without page parameters.
• Pages contain flat spans without events or properties. Rebuild the tree from parentId, or use assembleRunTracePages from @trigger.dev/core/v3, which also marks unfinished spans under a cancelled or failed parent the way the tree response does.
• A span can appear on two pages, once in progress and once finished. Keep the finished one.
• pagination.truncated means some spans or records were left out: paging stopped early (for example while an emergency span limit is in place), or a span had more records than one read allows.
• Send Accept-Encoding: gzip when you call the endpoint directly.

Authorizations

Authorization · string · header · required

Use a named environment API key. It starts with tr_dev_sk_, tr_prod_sk_, tr_stg_sk_, etc.

Create a named API key in the API Keys section of your Trigger.dev project dashboard. Choose the narrowest access preset that supports your integration.

Our TypeScript SDK will default to using the value of the TRIGGER_SECRET_KEY environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the configure function.

import { configure } from "@trigger.dev/sdk";

configure({ accessToken: "tr_dev_sk_1234" });

Path Parameters

runId · string · required

The ID of an run, starts with run_. The run ID will be returned when you trigger a run on a task.

Query Parameters

page[size] · integer

Turns on paging. Spans per page; values are clamped to 1,000–10,000. Defaults to 10,000 when only page[after] is sent.

Required range: x >= 1

page[after] · string

Turns on paging. The pagination.next cursor from the previous page, passed back unchanged. Omit it for the first page.

Response

200

application/json

Successful request. Without page parameters, the nested trace tree. With them, one page of flat spans.

Trace tree

Trace page

trace · object

Show child attributes