> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents.kolena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Agent Run (and Wait)

> Push data to an Agent Run and wait for results

#### Rate Limits

This endpoint is rate limited based on your Organization tier:

| Organization Tier | Rate Limit (requests/minute) |
| ----------------- | ---------------------------- |
| Starter           | 10                           |
| Professional      | 20                           |
| Enterprise        | 40                           |

Rate limits are applied per Organization.

#### Behavior

This endpoint accepts data to create an Agent Run.
If the results from all Prompts are available within the requested `timeout` 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](/api-reference/get-agent-run) later.

<Note>
  Compared to the [Add Agent Run](/api-reference/add-agent-run) endpoint, this endpoint is synchronous and attempts to wait for the Agent Run to complete before returning results.
  Requests are processed with higher priority when resources are available, but the endpoint is rate limited more strictly.
</Note>

#### 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](/api-reference/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](/api-reference/add-agent-run)) and poll for results


## OpenAPI

````yaml openapi.json POST /api/v1/client/agents/{agent_id}/runs/wait
openapi: 3.1.0
info:
  title: kolena
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/client/agents/{agent_id}/runs/wait:
    post:
      tags:
        - client
        - agents
      summary: Client Add Agent Run And Wait
      description: >-
        Push data to an Agent run and wait for results.

        This endpoint is rate limited based on your account tier:

        Trial: 10 requests/minute, Starter: 10 requests/minute, Professional: 20
        requests/minute, Enterprise: 40 requests/minute.

        Rate limits are applied per account.
      operationId: >-
        client_add_agent_run_and_wait_api_v1_client_agents__agent_id__runs_wait_post
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: integer
            title: Agent Id
        - name: timeout
          in: query
          required: false
          schema:
            type: integer
            maximum: 120
            minimum: 1
            description: How long to wait, in seconds, for the results from this Run.
            default: 60
            title: Timeout
          description: How long to wait, in seconds, for the results from this Run.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_client_add_agent_run_and_wait_api_v1_client_agents__agent_id__runs_wait_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRun'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                detail: >-
                  Rate limit exceeded for account (ID 123) in 'starter' tier.
                  Try again in 45.0 seconds. Remaining requests: 0
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: >-
                The number of requests remaining in the current rate limit
                window
              schema:
                type: integer
            X-RateLimit-Reset:
              description: >-
                The time at which the current rate limit window resets, in UTC
                epoch seconds
              schema:
                type: integer
      security:
        - HTTPBearer: []
components:
  schemas:
    Body_client_add_agent_run_and_wait_api_v1_client_agents__agent_id__runs_wait_post:
      properties:
        files:
          items:
            type: string
            format: binary
          type: array
          title: Files
          description: >-
            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:
          anyOf:
            - type: string
            - type: 'null'
          title: User Defined Id
          description: >-
            Optional user-defined identifier attached to this Run. Useful for
            tracking of Runs with external IDs.
      type: object
      required:
        - files
      title: >-
        Body_client_add_agent_run_and_wait_api_v1_client_agents__agent_id__runs_wait_post
    AgentRun:
      properties:
        agent_id:
          type: integer
          title: Agent Id
          description: The ID of the Agent being run.
        run_id:
          type: integer
          title: Run Id
          description: The ID of this Agent Run.
        user_defined_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Defined Id
          description: An optional user-defined ID attached to this Run.
        created:
          type: string
          format: date-time
          title: Created
          description: >-
            When this Run was created, formatted as an ISO 8601 timestamp (e.g.
            `2025-12-31T10:15:45+00:00`)
        updated:
          type: string
          format: date-time
          title: Updated
          description: >-
            When this Run was last updated, formatted as an ISO 8601 timestamp
            (e.g. `2025-12-31T10:15:45+00:00`)
        completed:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed
          description: >-
            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:
          items:
            type: string
          type: array
          title: Files
          description: List of filenames included in this Run.
        run_url:
          type: string
          title: Run Url
          description: Link to this Run on [agents.kolena.com](https://agents.kolena.com/).
        order:
          items:
            type: string
          type: array
          title: Order
          description: >-
            The order of Prompts in this Agent. When results are ready for a
            Prompt, it will be included in the `data` object.
        data:
          additionalProperties:
            $ref: '#/components/schemas/AgentRunResult'
          type: object
          title: Data
          description: >-
            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:
          $ref: '#/components/schemas/AgentRunStatus'
          description: The status of this Run.
        usage:
          anyOf:
            - $ref: '#/components/schemas/AgentCreditUsage'
            - type: 'null'
          description: >-
            For organizations with credit-based billing enabled, report the
            total credits used for this Run. `null` for organizations using
            page-based billing.
      type: object
      required:
        - agent_id
        - run_id
        - user_defined_id
        - created
        - updated
        - completed
        - files
        - run_url
        - order
        - data
        - status
      title: AgentRun
      examples:
        - 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: 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
                    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentRunResult:
      properties:
        status:
          $ref: '#/components/schemas/AgentRunStatus'
          description: >-
            The status of this Prompt, either `success` or `failed`. Prompts
            that are `running` are omitted from the `data` object.
        value:
          title: AnyValue
          description: The output value from this Prompt on this Run.
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: An error string if the Prompt failed to execute, otherwise `null`.
        metadata:
          anyOf:
            - $ref: '#/components/schemas/AgentRunResultMetadata'
            - type: 'null'
          description: >-
            Metadata associated with this Prompt run, including reasoning,
            citations, and confidence values.
        user_input:
          anyOf:
            - $ref: '#/components/schemas/CellResultUserInput'
            - type: 'null'
          description: Optional user-provided correction to this Prompt output.
        start_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Start Time
          description: ISO 8601 timestamp indicating when this Prompt started running.
        end_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Time
          description: ISO 8601 timestamp indicated when this Prompt completed.
        usage:
          anyOf:
            - $ref: '#/components/schemas/AgentCreditUsage'
            - type: 'null'
          description: Usage information for this Prompt.
      type: object
      required:
        - status
        - value
        - error
        - metadata
      title: AgentRunResult
    AgentRunStatus:
      type: string
      enum:
        - running
        - success
        - failed
      title: AgentRunStatus
    AgentCreditUsage:
      properties:
        credits_used:
          type: number
          title: Credits Used
          description: The credits used by this object.
      type: object
      required:
        - credits_used
      title: AgentCreditUsage
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentRunResultMetadata:
      properties:
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning
          description: Reasoning behind the `value` provided as a Prompt output.
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
          description: >-

            A confidence value on `[0, 1]` indicating uncertainty around the
            provided `value`. A confidence of 1 indicates that the model is
            highly certain of the result.
        citations:
          items:
            $ref: '#/components/schemas/AgentRunResultMetadataCitation'
          type: array
          title: Citations
          description: >-
            A list of citations, including documents and page numbers, used to
            produce the output `value`.
        url_citations:
          items:
            $ref: '#/components/schemas/AgentRunResultMetadataUrlCitation'
          type: array
          title: Url Citations
          description: >-
            A list of URL citations, including web pages and resources, used to
            produce the output `value`.
      type: object
      required:
        - reasoning
        - confidence
        - citations
      title: AgentRunResultMetadata
    CellResultUserInput:
      properties:
        data:
          anyOf:
            - $ref: '#/components/schemas/CellResultUserData'
            - type: 'null'
        data_updated:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Data Updated
        data_edited_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Data Edited By
      type: object
      title: CellResultUserInput
    AgentRunResultMetadataCitation:
      properties:
        file:
          type: string
          title: File
          description: The name of the file being referenced.
        pages:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Pages
          description: >-
            The relevant page(s) referenced by the model, or `null` if
            referencing a non-paginated file type.
        regions:
          anyOf:
            - items:
                $ref: '#/components/schemas/CitationRegion'
              type: array
            - type: 'null'
          title: Regions
          description: The regions of interest supporting the citations.
      type: object
      required:
        - file
        - pages
      title: AgentRunResultMetadataCitation
    AgentRunResultMetadataUrlCitation:
      properties:
        url:
          type: string
          title: Url
          description: The URL being referenced.
        title:
          type: string
          title: Title
          description: The title of the web page or resource.
        cited_text:
          type: string
          title: Cited Text
          description: The specific text from the URL that was cited.
      type: object
      required:
        - url
        - title
        - cited_text
      title: AgentRunResultMetadataUrlCitation
    CellResultUserData:
      properties:
        value:
          title: AnyValue
      type: object
      title: CellResultUserData
    CitationRegion:
      properties:
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
          description: The page where this supporting evidence appears.
        point:
          anyOf:
            - prefixItems:
                - type: integer
                - type: integer
              type: array
              maxItems: 2
              minItems: 2
            - type: 'null'
          title: Point
          description: >-
            The approximate position of the evidence on the page. [x, y]
            coordinates as percentages (0-100), where [0, 0] is the top-left and
            [100, 100] is the bottom-right.
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: A short excerpt or label of the supporting evidence.
      type: object
      required:
        - page
        - point
        - text
      title: CitationRegion
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`. The `<token>`
        represents your API key, which must be acquired from the Kolena
        platform.

````