Client List Agent Runs
curl --request GET \
  --url https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs \
  --header 'Authorization: Bearer <token>'
{
  "runs": [
    {
      "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
      }
    }
  ],
  "total_pages": 123,
  "page_number": 123,
  "page_size": 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

Query Parameters

​
page_number
integer
default:0

Optionally specify the index of the Runs page to fetch.

Required range: x >= 0
​
page_size
integer
default:50

Optionally specify the maximum number of Runs to fetch.

Required range: 0 <= x <= 1000
​
run_ids
integer[] | null

Optionally specify specific Run IDs to fetch.

​
status
enum<string> | null

Optionally specify the type of Runs to fetch, e.g. running or success.

Available options:
running,
success,
failed
​
user_defined_ids
string[] | null

Optionally specify the user_defined_ids of Runs to fetch.

Response

Successful Response

​
runs
AgentRun · object[]
required

The fetched page of Runs from this Agent.

​
total_pages
integer
required

The total number of pages of Runs for this Agent. Use the request arguments page_number and page_size to control which Runs are fetched.

​
page_number
integer
required

The number of the fetched page.

​
page_size
integer
required

The page size, i.e. number of Runs, fetched.