> ## 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.

# List Agent Events

> Page through an agent run's event log

<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 an agent's event log, newest first.

Events are the agent-side log: an id, a three-level severity, a message, and a timestamp. For the executor's own log lines, use `GET /agents/instances/{agent_id}/logs`.

## 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 events older than the one with this id. Pass the `next_cursor` of the previous page (or the id of its last event) to fetch the next page. Mutually exclusive with `before`.
</ParamField>

<ParamField query="before" type="string">
  Backward cursor: return events newer than the one with this id. Pass the id of the first event of the current page to walk back. Mutually exclusive with `after`.
</ParamField>

## Response

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

<ResponseField name="has_more" type="boolean" required>
  True when more events 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>

### Event object

<ResponseField name="id" type="string" required>
  Event id — the keyset cursor value for `after`/`before`.
</ResponseField>

<ResponseField name="level" type="string" required>
  Event severity for the agent event log: `info`, `warning`, or `error`.
</ResponseField>

<ResponseField name="message" type="string" required>
  The event message.
</ResponseField>

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

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

  ```bash cURL - Next Page theme={"system"}
  curl "$ATAI_API_URL/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/events?after=evt_01jc9q9m2x" \
    -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}"}
  events_url = f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/events"

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

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

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

      if not page["has_more"]:
          break
      cursor = page["next_cursor"]
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    `${process.env.ATAI_API_URL}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/events?limit=50`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
      }
    }
  );

  const body = await response.json();

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

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "data": [
      {
        "id": "evt_01jc9q9m2x",
        "level": "info",
        "message": "Run dispatched to executor.",
        "created_at": "2026-08-11T15:10:04Z"
      },
      {
        "id": "evt_01jc9q8w7b",
        "level": "info",
        "message": "Run created.",
        "created_at": "2026-08-11T15:10:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
  ```

  ```json 200 - Empty page 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 event `id` is this list's cursor value — pass it directly as `after` or `before`.
  * `after` and `before` are mutually exclusive — send at most one of them.
  * Events use the agent-side severity vocabulary (`info`, `warning`, `error`), which is narrower than the executor log levels returned by `/logs`.
</Note>