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-01T00:00:00",
  "updated": "2025-01-05T00:00: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
​
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)

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