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' \
--form files=@example-fileimport requests
url = "https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait"
files = { "files": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('files', '<string>');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"agent_id": 1,
"completed": "2025-01-01T12:02:00",
"created": "2025-01-01T12:00:00",
"data": {
"Another Example": {
"end_time": "2025-01-05T03:13:59.000013",
"metadata": {
"citations": [
{
"file": "demo2.csv"
}
],
"confidence": 1,
"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
],
"regions": [
{
"page": 2,
"point": [
20,
15
],
"text": "Account number"
}
]
}
],
"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
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"detail": "Rate limit exceeded for account (ID 123) in 'starter' tier. Try again in 45.0 seconds. Remaining requests: 0"
}Add Agent Run (and Wait)
Push data to an Agent Run and wait for results
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' \
--form files=@example-fileimport requests
url = "https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait"
files = { "files": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('files', '<string>');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents-api.kolena.com/api/v1/client/agents/{agent_id}/runs/wait")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"agent_id": 1,
"completed": "2025-01-01T12:02:00",
"created": "2025-01-01T12:00:00",
"data": {
"Another Example": {
"end_time": "2025-01-05T03:13:59.000013",
"metadata": {
"citations": [
{
"file": "demo2.csv"
}
],
"confidence": 1,
"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
],
"regions": [
{
"page": 2,
"point": [
20,
15
],
"text": "Account number"
}
]
}
],
"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
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"detail": "Rate limit exceeded for account (ID 123) in 'starter' tier. Try again in 45.0 seconds. Remaining requests: 0"
}Rate Limits
This endpoint is rate limited based on your Organization tier:| Organization Tier | Rate Limit (requests/minute) |
|---|---|
| Starter | 10 |
| Professional | 20 |
| Enterprise | 40 |
Behavior
This endpoint accepts data to create an Agent Run. If the results from all Prompts are available within the requestedtimeout period, the response will include the completed Agent Run with results.
Otherwise, the response will contain a status of running and a run_id which can be used to fetch the results later.
Handling Timeouts
If the Agent Run takes longer than the request timeout period to complete, this endpoint will return the Agent Run in arunning status. In such cases:
- The response will indicate the Run is still in progress
- 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:- Use smaller inputs - Upload inputs with minimal content and fewer prompts
- Disable “Data Analysis” - If your Agent has Data Analysis enabled, consider disabling it for faster processing
- Batch your requests - For large volumes of data, consider using the non-waiting version (Add Agent Run) and poll for results
Authorizations
Bearer authentication header of the form Bearer <token>. The <token> represents your API key, which must be acquired from the Kolena platform.
Path Parameters
Query Parameters
How long to wait, in seconds, for the results from this Run.
1 <= x <= 120Body
Response
Successful Response
The ID of the Agent being run.
The ID of this Agent Run.
An optional user-defined ID attached to this Run.
When this Run was created, formatted as an ISO 8601 timestamp (e.g. 2025-12-31T10:15:45+00:00)
When this Run was last updated, formatted as an ISO 8601 timestamp (e.g. 2025-12-31T10:15:45+00:00)
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.
List of filenames included in this Run.
Link to this Run on agents.kolena.com.
The order of Prompts in this Agent. When results are ready for a Prompt, it will be included in the data object.
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.
Show child attributes
Show child attributes
The status of this Run.
running, success, failed For organizations with credit-based billing enabled, report the total credits used for this Run. null for organizations using page-based billing.
Show child attributes
Show child attributes
Was this page helpful?
