# Run an agent
Source: https://docs.simpleserve.ai/docs/api-reference/runs/post-runs

Method: POST /v1/runs
Base URL: https://api.simpleserve.ai

```json
{
  "path": "/v1/runs",
  "method": "POST",
  "tags": [
    "Runs"
  ],
  "operationId": "createRun",
  "summary": "Run an agent",
  "description": "Starts new work or continues prior work.\n\nSend `session_id` to continue prior work. Omit it to create a session.\nEach request creates a new run inside that session.\n\nThe default request waits for a terminal result. Set `background: true`\nto return an accepted run immediately. Set `stream: true` to receive\nServer-Sent Events. `background` and `stream` cannot both be true.\n\nSimpleServe can return `202` when work continues after the request wait\nends. Retrieve the Run from the `location` response header.\n\nSimpleServe authorizes `max_cost_usd` when present. When it is absent, SimpleServe\nauthorizes the agent's published maximum. A smaller limit is accepted\nwhen it covers the agent's published minimum.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/IdempotencyKey"
    },
    {
      "$ref": "#/components/parameters/LastEventId"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateRunRequest"
        },
        "examples": {
          "text": {
            "summary": "Start a text-first run",
            "value": {
              "agent": "acme/construction-researcher",
              "input": "Find hotel projects over $25M breaking ground in Miami.",
              "max_cost_usd": 3
            }
          },
          "continue": {
            "summary": "Continue prior work",
            "value": {
              "agent": "acme/construction-researcher",
              "input": "Keep only projects expected to start within six months.",
              "session_id": "ses_01JXYZ1234567890",
              "max_cost_usd": 3
            }
          },
          "with_files": {
            "summary": "Run with uploaded files",
            "value": {
              "agent": "acme/document-reviewer",
              "input": "Compare these documents and return a change report.",
              "files": [
                "file_01JXYZ1234567890",
                "file_01JXYZ0987654321"
              ],
              "max_cost_usd": 5
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "A terminal run, or an event stream when `stream` is true.\n",
      "headers": {
        "x-request-id": {
          "$ref": "#/components/headers/RequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Run"
          },
          "examples": {
            "completed": {
              "$ref": "#/components/examples/CompletedRunExample"
            },
            "cost_limit": {
              "$ref": "#/components/examples/LimitReachedRunExample"
            }
          }
        },
        "text/event-stream": {
          "schema": {
            "description": "UTF-8 Server-Sent Events. The SSE `event` field matches the\nJSON `type` field. Each `data` value matches `RunStreamEvent`.\n",
            "allOf": [
              {
                "$ref": "#/components/schemas/RunStreamEvent"
              }
            ]
          },
          "examples": {
            "text_delta": {
              "summary": "A text output delta",
              "value": {
                "type": "output.text.delta",
                "run_id": "run_01JXYZ1234567890",
                "output_index": 0,
                "delta": "I found "
              }
            }
          }
        }
      }
    },
    "202": {
      "description": "The Run was accepted and continues in the background.",
      "headers": {
        "location": {
          "description": "URL for retrieving the run.",
          "schema": {
            "type": "string",
            "format": "uri-reference"
          }
        },
        "retry-after": {
          "description": "Suggested polling delay in seconds.",
          "schema": {
            "type": "integer",
            "minimum": 1
          }
        },
        "x-request-id": {
          "$ref": "#/components/headers/RequestId"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Run"
          },
          "examples": {
            "accepted": {
              "$ref": "#/components/examples/AcceptedRunExample"
            }
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "402": {
      "$ref": "#/components/responses/PaymentRequired"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "409": {
      "$ref": "#/components/responses/Conflict"
    },
    "413": {
      "$ref": "#/components/responses/PayloadTooLarge"
    },
    "422": {
      "$ref": "#/components/responses/UnprocessableEntity"
    },
    "429": {
      "$ref": "#/components/responses/RateLimited"
    },
    "500": {
      "$ref": "#/components/responses/InternalError"
    },
    "502": {
      "$ref": "#/components/responses/ProviderError"
    },
    "503": {
      "$ref": "#/components/responses/ProviderUnavailable"
    },
    "504": {
      "$ref": "#/components/responses/ProviderTimeout"
    }
  }
}
```