---
title: "Run agent"
url: "https://developers.bynder.com/apis/agents/versions/f5aecf98-613e-4ae8-b26a-ec2cdf804b2c/operations/runAgentExecution"
---

> Full API specification: https://developers.bynder.com/apis/agents/versions/f5aecf98-613e-4ae8-b26a-ec2cdf804b2c.md

# Run agent

`POST` `/api/1/agent/executions`

Operation ID: `runAgentExecution`

Runs one or more agents on assets. Send one item per agent, each with the asset list to process. The request is accepted as a whole: agents that could not be started are listed in `error` in the response, with the reason, and the ones that did start are listed in `success`.

## Request body (required)

Content types: `application/json`

## Responses

- `202` - Execution(s) accepted for processing. The response lists the executions that were created, the requests that failed, and a summary.
- `400` - The request body failed validation
- `401` - Missing or invalid bearer token
- `403` - Caller lacks the required permission for this operation
- `429` - Caller exceeded its configured request rate
- `5XX` - Gateway or a downstream service failed to process the request

## OpenAPI definition

```yaml
openapi: 3.0.3
info:
  title: AI Agents
  version: "1.0"
servers:
  - url: https://{your-bynder-domain}/
paths:
  /api/1/agent/executions:
    post:
      tags:
        - Executions
      summary: Run agent
      operationId: runAgentExecution
      description: "Runs one or more agents on assets. Send one item per agent, each
        with the asset list to process. The request is accepted as a whole:
        agents that could not be started are listed in `error` in the response,
        with the reason, and the ones that did start are listed in `success`."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecutionRequest"
      responses:
        "202":
          description: Execution(s) accepted for processing. The response lists the
            executions that were created, the requests that failed, and a
            summary.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionResult"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        5XX:
          $ref: "#/components/responses/ServerError"
security:
  - bearerAuth: []
components:
  schemas:
    ExecutionRequest:
      type: array
      description: An array of per-agent run requests, not a single object. Each item
        must include its own `agentId`.
      minItems: 1
      maxItems: 100
      items:
        $ref: "#/components/schemas/ExecutionRequestItem"
    ExecutionResult:
      type: object
      properties:
        success:
          type: array
          items:
            type: object
            properties:
              agentId:
                type: string
              name:
                type: string
              agentExecutionId:
                type: string
                format: uuid
              capabilities:
                type: array
                items:
                  type: string
          description: The executions that were created.
        error:
          type: array
          items:
            type: object
            properties:
              agentId:
                type: string
              name:
                type: string
                nullable: true
              capabilities:
                type: array
                nullable: true
                items:
                  type: string
              errorType:
                type: string
          description: The run requests that failed.
        executionSummary:
          type: object
          additionalProperties:
            type: integer
            format: int32
          description: Counts of run requests by outcome.
      description: The outcome of a run request.
    ExecutionRequestItem:
      type: object
      description: A request to run one agent.
      required:
        - agentId
        - assetIds
      properties:
        agentId:
          type: string
          format: uuid
        assetIds:
          type: array
          minItems: 1
          maxItems: 10000
          items:
            type: string
            format: uuid
        agentExecutionName:
          type: string
          maxLength: 256
        workspaceBatchId:
          type: string
          format: uuid
          nullable: true
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  responses:
    ValidationError:
      description: The request body failed validation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Forbidden:
      description: Caller lacks the required permission for this operation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    TooManyRequests:
      description: Caller exceeded its configured request rate
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ServerError:
      description: Gateway or a downstream service failed to process the request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```