Skip to main content
Client Add Agent Run And Wait
curl --request POST \
  --url https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data'
{
  "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 based on your organization tier:
Organization TierRate Limit (requests/minute)
Starter10
Professional20
Enterprise40
Rate limits are applied per organization.

Handling Timeouts

If the Agent Run takes longer than the request timeout period to complete, this endpoint will return the Agent Run in a running status. In such cases:
  1. The response will indicate the Run is still in progress
  2. You can use the Get Agent Run endpoint to fetch the results later by providing the same run_id

Tips to Avoid Timeouts

To reduce the likelihood of timeouts when using this endpoint:
  1. Use smaller inputs - Upload inputs with minimal content and fewer prompts
  2. Disable “Data Analysis” - If your Agent has Data Analysis enabled, consider disabling it for faster processing
  3. Batch your requests - For large volumes of data, consider using the non-waiting version (Add Agent Run) and poll for results

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

timeout
integer
default:60

How long to wait, in seconds, for the results from this Run.

Required range: 1 <= x <= 120

Body

multipart/form-data
files
file[]
required

List of files for the run. A single request can have a maximum of 150 files. Each file can have maximum 125MB.

user_defined_id
string | null

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-10-08T20:14:29.472247+00:00)

updated
string<date-time>
required

When this Run was last updated, formatted as an ISO 8601 timestamp (e.g. 2025-10-08T20:14:29.472247+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.

I