> ## Documentation Index > Fetch the complete documentation index at: https://docs.mercora.io/llms.txt > Use this file to discover all available pages before exploring further. # Start an automation run > Starts a run of an automation whose trigger is the API. The run works in Mercora; anything it would change waits for a person's approval there. 201 a new run, 200 a retry of an external_id already used with the same body, 404 no such automation in this workspace, 409 the automation doesn't run from the API or the external_id was used with another body, 429 the workspace's daily run budget is used up. Scope: `automations`. ## OpenAPI ````yaml /api-reference/openapi.json post /agents/{id}/run openapi: 3.1.0 info: title: Mercora API version: v1 description: >- Your own systems call Mercora with a workspace API key. Bodies are JSON with a fixed schema; unknown fields are refused. Errors are `{ error }`, plus `issues` on a 422. A create carries your own `external_id`: sending it again returns what was created the first time. servers: - url: https://{workspace}.mercora.io/api/v1 description: Your Mercora workspace variables: workspace: default: your-company description: Your workspace subdomain security: [] tags: - name: Hedge requests description: >- Read the hedge books and positions, push hedge requests into the Inbox, read where they stand. - name: Automations description: >- Start runs of automations set to run from the API. What a run would change still waits for a person in Mercora. paths: /agents/{id}/run: post: tags: - Automations summary: Start an automation run description: >- Starts a run of an automation whose trigger is the API. The run works in Mercora; anything it would change waits for a person's approval there. 201 a new run, 200 a retry of an external_id already used with the same body, 404 no such automation in this workspace, 409 the automation doesn't run from the API or the external_id was used with another body, 429 the workspace's daily run budget is used up. Scope: `automations`. operationId: runAutomation parameters: - schema: type: string description: The automation's id. required: true description: The automation's id. name: id in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AutomationRunRequest' example: external_id: PO-2026-0412 input: purchase_order: PO-2026-0412 responses: '200': description: This external_id already started this run (same body). content: application/json: schema: $ref: '#/components/schemas/Error' '201': description: The run started. content: application/json: schema: $ref: '#/components/schemas/AutomationRun' example: id: 1c9e2f3a-4b5d-4e6f-9a0b-1c2d3e4f5a6b agent_id: 8b0d1c2e-3f4a-4b5c-8d6e-7f8091a2b3c4 status: running started_at: '2026-10-12T08:00:00.000Z' '400': description: Body is not JSON. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Key missing, unknown or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- The key lacks the `automations` scope, or the resource's module is off for the workspace. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such automation in this workspace. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The automation doesn't run from the API, or the external_id was used with another body. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Body failed its schema; `issues` lists each field. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- The workspace's daily run budget is used up; it resets at midnight UTC. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Ours, logged with the workspace and key. Retrying is safe. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: AutomationRunRequest: type: object properties: external_id: type: string minLength: 1 maxLength: 200 description: >- Your own id for this request. Sending the same external_id and body again returns the run it started. input: type: object additionalProperties: {} description: >- Anything the automation should work from, handed to it as the request that started the run. required: - external_id additionalProperties: false Error: type: object properties: error: type: string issues: type: array items: type: object properties: field: type: - string - 'null' message: type: string required: - field - message description: 'On a 422: one entry per field that failed.' required: - error AutomationRun: type: object properties: id: type: string description: The run's id. agent_id: type: string status: type: string enum: - running - waiting - done - failed - cancelled description: 'waiting: a person has to approve or answer something in Mercora.' started_at: type: - string - 'null' required: - id - agent_id - status - started_at securitySchemes: bearerAuth: type: http scheme: bearer description: A workspace API key (mk_…), made under Settings → Administration → API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.