> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "Run logs"
description: "Read structured logs emitted during a run, across every worker and step."
method: "GET"
endpoint: "/api/v1/runs/:runId/logs"
order: 3
last_verified: 2026-07-27
---

<ApiEndpoint
  method="GET"
  endpoint="/api/v1/runs/:runId/logs"
  description="Read structured logs emitted during a run, across every worker and step."
>
  <section>
    ### Path and query parameters

    <ApiAttribute name="runId" type="string" description="The run's UUID." required={true} />
    <ApiAttribute name="workspace_id" type="string" description="The owning workspace's UUID. Also accepted as the X-Workspace-ID header." required={true} />
    <ApiAttribute name="since" type="string" description="Start of the time range, as nanoseconds or RFC 3339." required={false} />
    <ApiAttribute name="until" type="string" description="End of the time range, as nanoseconds or RFC 3339." required={false} />
    <ApiAttribute name="limit" type="integer" description="Maximum log lines to return." required={false} />
    <ApiAttribute name="service" type="string" description="Filter to one or more service names." required={false} />
    <ApiAttribute name="log_source" type="string" description="Filter to one or more log sources." required={false} />
  </section>

  <Callout type="info">
Requests without a resolvable workspace — no `workspace_id` query parameter, `X-Workspace-ID` header, or route-level workspace context — get a `403` with the message "Workspace context is required for this action".
  </Callout>

  <section>
    ### Request example

    <MultiLanguageCodeBlock
      languages={["bash", "javascript"]}
      value={[
        {
          language: 'bash',
          code: `curl "https://api.agnt5.com/api/v1/runs/7f6e5d4c-.../logs?limit=100" \\
  -H "X-API-KEY: {api_key}" \\
  -H "X-Workspace-ID: {workspace_id}"`
        },
        {
          language: 'javascript',
          code: `fetch(\`https://api.agnt5.com/api/v1/runs/\${runId}/logs?limit=100\`, {
  headers: { 'X-API-KEY': apiKey, 'X-Workspace-ID': workspaceId }
})`
        }
      ]}
    />

    ```json {{ title: 'Response' }}
    {
      "items": [
        {
          "ts_ns": 1753612801123000000,
          "service": "invoice-processor-worker",
          "scope": "agnt5.sdk",
          "severity": "INFO",
          "body": "Step process_invoice.extract_fields completed",
          "trace_id": "4f6a2e1b8c9d7f3a5e2b1c4d6a8f9e0b",
          "span_id": "a1b2c3d4e5f60718"
        }
      ],
      "count": 1
    }
    ```

    This endpoint doesn't support offset-based pagination. To page through a larger result set, narrow `since`/`until` to the time range after the last line you received.
  </section>
</ApiEndpoint>