Skip to main content

​
Overview

The Komos public API lets you launch saved browser tasks, observe their progress, stream execution logs, and cancel them programmatically. Each run executes asynchronously—enqueue a task, poll for status or subscribe via webhooks, and consume the outputs once the run reaches a terminal state.

​
Base URLs

  • Production: https://api.komos.ai
Komos does not operate a staging environment; target the production host for all integrations. All endpoints are prefixed with /public/v1. When previewing the docs locally, point the API tester to your tunnel (https://api-komos.ngrok.app) so browser requests reach your development stack.

​
Endpoints

  • POST /public/v1/tasks/{taskId}/runs — queue an asynchronous run for a saved task (idempotent with clientRequestId).
  • GET /public/v1/tasks/{taskId}/runs — list the 50 most recent runs for a task, newest first.
  • GET /public/v1/task-runs/{runId} — fetch the latest status for a single run.
  • GET /public/v1/task-runs/{runId}/logs — retrieve ordered log entries captured while the run executed.
  • POST /public/v1/task-runs/{runId}/cancel — request cancellation for a pending or running task.

​
Authentication

Authenticate using an organization-scoped API key issued from the Komos dashboard. Send the secret in the Authorization header using the Bearer scheme: 
Authorization: Bearer sk_live_your_api_key
Requests without a valid key return 401 Unauthorized.

​
Idempotency

POST /public/v1/tasks/{taskId}/runs supports idempotent retries via the optional clientRequestId field. Repeat the call with the same value to receive 200 OK and the previously created run instead of launching a duplicate.

​
Run resource

Successful responses return a run object shaped like the example below. 
{
  "id": "9c77d908-7bf4-4e7f-9a20-2c5e7fdf2e94",
  "taskId": "79c6b1aa-24d1-45b3-8c94-9a2e2a2f55bc",
  "status": "RUNNING",
  "triggerType": "api",
  "timestamps": {
    "createdAt": "2025-10-14T18:21:52.123Z",
    "startedAt": "2025-10-14T18:22:03.481Z",
    "finishedAt": null
  },
  "progress": {
    "currentStep": 2,
    "stepsTotal": 5
  },
  "inputs": {
    "url": "https://example.com/orders/48219"
  },
  "outputs": {},
  "logsUrl": "https://api.komos.ai/public/v1/task-runs/9c77d908-7bf4-4e7f-9a20-2c5e7fdf2e94/logs",
  "error": null,
  "cancelReason": null
}
  • status values: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED.
  • triggerType is one of manual, schedule, or api.
  • logsUrl resolves to GET /public/v1/task-runs/{runId}/logs when backend_public_url is configured for your organization.

​
Error handling

Errors follow the standard FastAPI structure:
  • Validation issues return 400 Bad Request with {"detail": "invalid_task_id"}.
  • Missing resources return 404 Not Found, e.g., {"detail": "run_not_found"}.
  • Usage limits return 402 Payment Required with additional details.
  • Transient queue issues respond with 503 Service Unavailable; retry with exponential backoff.

​
Webhooks

Need near-real-time notifications? Configure outbound webhooks from the dashboard to receive run status and log events. Delivery cadence, headers, and payload schemas are detailed in api-reference/webhooks/overview. Refer to the endpoint pages for full schemas and examples.