Client Get Agent Run
curl --request GET \
  --url https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/{run_id} \
  --header 'Authorization: Bearer <token>'
{
  "agent_id": 1,
  "created": "2025-01-01T00:00:00",
  "data": {
    "Another Example": {
      "end_time": "2025-01-05T03:13:59.000013",
      "metadata": {
        "citations": [
          {
            "file": "demo2.csv"
          }
        ],
        "confidence": 0.9,
        "reasoning": "The order amount is listed in demo2.csv",
        "url_citations": []
      },
      "start_time": "2025-01-05T03:13:45.000051",
      "status": "success",
      "usage": {
        "credits_used": 0.071
      },
      "value": 123
    },
    "Example Prompt": {
      "end_time": "2025-01-05T03:05:10.000102",
      "metadata": {
        "citations": [
          {
            "file": "demo1.pdf",
            "pages": [
              2,
              5
            ]
          }
        ],
        "confidence": 1,
        "reasoning": "Looking at file demo1.pdf, ...",
        "url_citations": [
          {
            "cited_text": "Example text from website",
            "title": "Kolena Example",
            "url": "https://example.com/kolena"
          }
        ]
      },
      "start_time": "2025-01-05T03:05:05.000057",
      "status": "success",
      "usage": {
        "credits_used": 0.052
      },
      "value": "foo"
    }
  },
  "files": [
    "demo1.pdf",
    "demo2.csv"
  ],
  "order": [
    "Example Prompt",
    "Another Example"
  ],
  "run_id": 1,
  "run_url": "https://agents.kolena.com/my_org/agents/1/runs/1",
  "status": "success",
  "updated": "2025-01-05T00:00:00",
  "usage": {
    "credits_used": 0.123
  }
}

Rate Limits

This endpoint is rate limited to 1,200 requests per minute per user.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>. The <token> represents your API key, which must be acquired from the Kolena platform.

Path Parameters

agent_id
integer
required
run_id
integer
required

Response

Successful Response

agent_id
integer
required

The ID of the Agent being run.

run_id
integer
required

The ID of this Agent Run.

user_defined_id
string | null
required

An optional user-defined ID attached to this Run.

created
string<date-time>
required

When this Run was created, formatted as an ISO 8601 timestamp (e.g. 2025-09-09T23:19:55.691799+00:00)

updated
string<date-time>
required

When this Run was last updated, formatted as an ISO 8601 timestamp (e.g. 2025-09-09T23:19:55.691799+00:00)

files
string[]
required

List of filenames included in this Run.

run_url
string
required

Link to this Run on agents.kolena.com.

order
string[]
required

The order of Prompts in this Agent. When results are ready for a Prompt, it will be included in the data object.

data
object
required

The output data from completed Prompts, keyed on Prompt name.

Once a Prompt is completed (status success or failed), it will be included in this object. Any running prompts are omitted.

status
enum<string>
required

The status of this Run.

Available options:
running,
success,
failed
usage
object | null

For organizations with credit-based billing enabled, report the total credits used for this Run. null for organizations using page-based billing.