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

> Page through the output artifacts an agent run produced

<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 a run's output refs, newest first.

Results come from the executor (JOS job outputs), so each entry names the output port it was written to and points at the stored file. The list is empty for a noop run.

## 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 results older than this page. Pass the previous page's `next_cursor`. Opaque — not a result id; never compute on it. Mutually exclusive with `before`.
</ParamField>

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

## Response

<ResponseField name="data" type="array" required>
  The page, newest first. Each entry is one artifact the run produced.
</ResponseField>

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

### Result entry object

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

<ResponseField name="port_name" type="string" required>
  Executor output port the result was written to.
</ResponseField>

<ResponseField name="data" type="object" required>
  The stored file this result points at.
</ResponseField>

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

<ResponseField name="expires_at" type="string">
  When the result expires; `null` when it does not.
</ResponseField>

### File ref object (`data`)

<ResponseField name="ref" type="string" required>
  Fetchable reference to the bytes — a presigned URL, or a data-service ref that has to be downloaded through the authenticated proxy.
</ResponseField>

<ResponseField name="filename" type="string" required>
  Name of the stored file.
</ResponseField>

<ResponseField name="file_extension" type="string">
  File extension; `null` when unknown.
</ResponseField>

<ResponseField name="file_type" type="string">
  File type; `null` when unknown.
</ResponseField>

<ResponseField name="num_bytes" type="integer">
  Size of the file in bytes; `null` when unknown.
</ResponseField>

<ResponseField name="file_attributes" type="object">
  Executor-recorded attributes. Carries `job_output.status`, which marks a result written by a run that only partially succeeded.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl "$ATAI_API_URL/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/results?limit=50" \
    -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}"}
  results_url = f"{base_url}/agents/instances/agt_01jc9q8v5nm3ry7t2bkz4dhs6f/results"

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

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

      page = response.json()
      for result in page["data"]:
          file_ref = result["data"]
          print(f"{result['port_name']}: {file_ref['filename']} -> {file_ref['ref']}")

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

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

  const body = await response.json();

  if (response.ok) {
    body.data.forEach(result => {
      console.log(`${result.port_name}: ${result.data.filename} -> ${result.data.ref}`);
    });
  } else {
    console.error('Error:', body.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "data": [
      {
        "id": "out_01jc9q9m6f",
        "port_name": "predictions",
        "data": {
          "ref": "https://<presigned-url>",
          "filename": "predictions.ndjson",
          "file_extension": "ndjson",
          "file_type": null,
          "num_bytes": 48213,
          "file_attributes": {
            "job_output.status": "<status>"
          }
        },
        "expires_at": "2026-08-12T15:18:41Z",
        "created_at": "2026-08-11T15:18:41Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
  ```

  ```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 result id. Pass `next_cursor` back verbatim; never derive it from `data[last].id`.
  * `ref` may be a presigned URL or a data-service ref — the latter must be downloaded through the authenticated proxy.
  * Check `file_attributes["job_output.status"]`: it marks a result written by a run that only partially succeeded.
  * A noop run produces no outputs, so `data` comes back empty.
</Note>