> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Get Agent Logs

> Page through an agent run's executor-sourced log lines

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.9](/release-notes/1.1.x#v1-1-9) or later of the Archetype platform.
</Callout>

## Overview

This endpoint returns a page of run log entries, newest first.

Log lines come from the executor (JOS job events) rather than from the agent event log, so they carry the executor's own severity vocabulary and event kinds. The list is empty for a noop run. Filter by severity, or search the message and event type.

## Request

<ParamField path="agent_id" type="string" required>
  Agent `agt_` id.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Page size. Minimum `1`, maximum `1000`.
</ParamField>

<ParamField query="after" type="string">
  Forward cursor: return log lines older than this page. Pass the previous page's `next_cursor`. Opaque — not a log id; never compute on it. Mutually exclusive with `before`.
</ParamField>

<ParamField query="before" type="string">
  Backward cursor: return log lines newer than this page. Opaque, as `after` is. Mutually exclusive with `after`.
</ParamField>

<ParamField query="level" type="string">
  Filter to a single severity. Omit for all severities. One of `INFO`, `WARN`, `ERROR`, `SUCCESS`, `FAILED` — any case is accepted, and `warning` is accepted for `warn`.
</ParamField>

<ParamField query="search" type="string">
  Case-insensitive substring match over the line's message and event type. Omit for no search filter.
</ParamField>

## Response

<ResponseField name="data" type="array" required>
  The page, newest first. Each entry is a log line.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  True when more log lines exist beyond this page in the direction of travel.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Cursor for the next page in the same direction — pass it as `after` when paging forward, or as `before` when you supplied `before`. `null` when `has_more` is false.
</ResponseField>

### Log entry object

One executor-sourced log line for a run (a JOS job event).

<ResponseField name="id" type="string" required>
  Executor-assigned log id. Stable, but not this list's cursor.
</ResponseField>

<ResponseField name="level" type="string" required>
  Severity of the line, in the executor's vocabulary: `INFO`, `WARN`, `ERROR`, `SUCCESS`, or `FAILED`.
</ResponseField>

<ResponseField name="event_type" type="string" required>
  Executor's event kind, e.g. `status_change`.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  When the line was logged (date-time).
</ResponseField>

<ResponseField name="message" type="string">
  The log message; `null` when the event carries none.
</ResponseField>

<ResponseField name="index" type="integer">
  Index of the worker that logged the line, when it came from one.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl "$ATAI_API_URL/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/logs?limit=50" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```bash cURL - Errors Only theme={"system"}
  curl "$ATAI_API_URL/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/logs?level=ERROR" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```bash cURL - Search theme={"system"}
  curl "$ATAI_API_URL/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/logs?search=status_change" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```python Python theme={"system"}
  import os
  import requests

  base_url = os.environ["ATAI_API_URL"]
  api_key = os.environ["ATAI_API_KEY"]
  headers = {"Authorization": f"Bearer {api_key}"}
  logs_url = f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/logs"

  cursor = None
  while True:
      params = {"limit": 100}
      if cursor:
          params["after"] = cursor

      response = requests.get(logs_url, headers=headers, params=params)
      if response.status_code != 200:
          print(f"Error: {response.json()['errors']}")
          break

      page = response.json()
      for line in page["data"]:
          print(f"[{line['level']}] {line['event_type']}: {line.get('message')}")

      if not page["has_more"]:
          break
      # The cursor is opaque — pass it back verbatim.
      cursor = page["next_cursor"]
  ```

  ```javascript JavaScript theme={"system"}
  const params = new URLSearchParams({ limit: '50', level: 'ERROR' });

  const response = await fetch(
    `${process.env.ATAI_API_URL}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/logs?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
      }
    }
  );

  const body = await response.json();

  if (response.ok) {
    body.data.forEach(line => {
      console.log(`[${line.level}] ${line.event_type}: ${line.message}`);
    });
  } else {
    console.error('Error:', body.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "data": [
      {
        "id": "log_01jc9q9m4d",
        "level": "SUCCESS",
        "event_type": "status_change",
        "message": "Job completed.",
        "index": null,
        "created_at": "2026-08-11T15:18:41Z"
      },
      {
        "id": "log_01jc9q9k8r",
        "level": "INFO",
        "event_type": "status_change",
        "message": "Worker started.",
        "index": 0,
        "created_at": "2026-08-11T15:10:07Z"
      }
    ],
    "has_more": true,
    "next_cursor": "<opaque-cursor>"
  }
  ```

  ```json 200 - Empty (noop run) theme={"system"}
  {
    "data": [],
    "has_more": false,
    "next_cursor": null
  }
  ```

  ```json 400 - Invalid cursor theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Invalid cursor.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 404 - Agent not found theme={"system"}
  {
    "errors": [
      {
        "code": "<error_code>",
        "message": "Agent not found.",
        "suggestion": null,
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>

## Important Notes

<Note>
  * The cursor here is **opaque** and is not a log id. Pass `next_cursor` back verbatim; never derive it from `data[last].id` or compute on it.
  * `after` and `before` are mutually exclusive — send at most one of them.
  * `level` uses the executor's vocabulary, which includes `SUCCESS` and `FAILED` — these have no equivalent in the agent event log's three levels.
  * A noop run produces no executor logs, so `data` comes back empty.
</Note>