Skip to main content
Client Add Agent Run
curl --request POST \
  --url https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'files=<string>' \
  --form files.items='@example-file'
{
  "agent_id": 1,
  "run_id": 1,
  "created": "2025-01-01T12:00:00",
  "updated": "2025-01-05T00:00:00",
  "completed": "2025-01-01T12:02:00",
  "files": [
    "demo1.pdf",
    "demo2.csv"
  ],
  "run_url": "https://agents.kolena.com/my_org/agents/1/runs/1",
  "order": [
    "Example Prompt",
    "Another Example"
  ],
  "data": {},
  "status": "running"
}
Rate Limit: This endpoint is limited to 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

Body

multipart/form-data
​
files
file[]
required

List of files for the run. A single request can have a maximum of 300 files. Each file can have maximum size of 250MB.

​
user_defined_id
string | null

Optional user-defined identifier attached to this Run. Useful for tracking of Runs with external IDs.

​
due_date
string<date-time> | null

Optionally specify a due date for this Run as an ISO 8601 timestamp (e.g. 2025-12-31T10:15:45+00:00). When a due date is specified, Kolena will attempt to ensure that all Prompts have completed on this Run before its due date.

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-12-31T10:15:45+00:00)

​
updated
string<date-time>
required

When this Run was last updated, formatted as an ISO 8601 timestamp (e.g. 2025-12-31T10:15:45+00:00)

​
completed
string<date-time> | null
required

When all Prompts in this Run completed, formatted as an ISO 8601 timestamp (e.g. 2025-12-31T10:15:45+00:00).

The time between created and completed is the total time taken by the Agent for this Run. Will be null if the Run is still in progress and for historical Runs created before March 2026.

​
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
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
AgentCreditUsage · object

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