--- title: "Start an endpoint run" method: POST path: "/v1/run" tags: ["Runs"] --- # Start an endpoint run `POST /v1/run` Start an execution of an endpoint. For a sync COMPLETED run the HTTP status FAITHFULLY MIRRORS the provider's own status (2xx → 2xx, provider 4xx/5xx → 4xx/5xx, request-timeout → 504); the body always carries the full run. A control gate returns a 200 BLOCKED run, and a run that exceeds its time budget returns 408 (TIMED_OUT). Async endpoints return a 202 acceptance ack — poll GET /v1/runs/{runId} for the result. ## Request body - RunRequest - `provider` string, required — Provider slug. - `endpoint` string, required — Endpoint path within the provider. - `input` object — Composite endpoint input — body + URL query + URL path. All sub-fields optional. - `body` object — Request body fields. - `queryParams` object — URL query string parameters. - `pathParams` object — URL path placeholder substitutions (e.g. {id} in `/users/{id}`). ## Response `200` Terminal run — COMPLETED (sync execution, when the provider responded 2xx) or BLOCKED (a workspace control gate rejected the run). A COMPLETED run with a non-2xx provider status is returned with that same HTTP status and this body shape — EXCEPT a provider 402 (the upstream vendor's payment/quota failure, not your wallet), which is returned as 502. - union - RunCompleted - `runId` string, required - `provider` string, required - `endpoint` string, required - `status` 'READY' | 'RUNNING' | 'STOPPING' | 'COMPLETED' | 'FAILED' | 'BLOCKED' | 'STOPPED' | 'TIMED_OUT', required - `output` unknown - `providerResponse` ProviderResponse, required - `httpStatus` integer — HTTP status from the provider (e.g. 200, 400, 404, 429, 500). - `error` unknown - `price` Price, required — User-facing price (markup applied). - `type` string, required - `amount` object, required - `value` number, required - `currency` 'USD', required - `flatFee` object - `value` number, required - `currency` 'USD', required - `period` object - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - `per` union - object - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - number - `unit` 'token' | 'character' | 'second' - `default` union - object - `type` 'PER_CALL', required - `amount` object, required - `value` number, required - `currency` 'USD', required - object - `type` 'PER_RESULT', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `flatFee` object - `value` number, required - `currency` 'USD', required - object - `type` 'METERED', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `per` object, required - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - object - `type` 'PER_UNIT', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `per` number, required - `unit` 'token' | 'character' | 'second', required - `selectors` object[] - `label` string, required - `key` string, required - `in` 'body' | 'queryParam' | 'pathParam' | 'output', required - `variants` object[] - `when` object, required - `price` union, required - object - `type` 'PER_CALL', required - `amount` object, required - … - object - `type` 'PER_RESULT', required - `amount` object, required - … - `flatFee` object - … - object - `type` 'METERED', required - `amount` object, required - … - `per` object, required - … - object - `type` 'PER_UNIT', required - `amount` object, required - … - `per` number, required - `unit` 'token' | 'character' | 'second', required - `label` string - `tiers` object[] - `label` string, required - `when` object, required - `selector` object - `label` string, required - `key` string, required - `in` 'body' | 'queryParam' | 'pathParam' | 'output', required - `price` union, required - object - `type` 'PER_CALL', required - `amount` object, required - … - object - `type` 'PER_RESULT', required - `amount` object, required - … - `flatFee` object - … - object - `type` 'METERED', required - `amount` object, required - … - `per` object, required - … - object - `type` 'PER_UNIT', required - `amount` object, required - … - `per` number, required - `unit` 'token' | 'character' | 'second', required - `notes` string[] - `billing` RunBilling - `reportedCost` object, required — What the user pays for this run. - `currency` 'USD', required - `value` integer, required - `unit` 'MICRO_DOLLAR' | 'CENT' | 'DOLLAR', required - `resultCount` number - `billedUnits` number - `resources` object[] - `action` 'PROVISIONED' | 'PROVISION_FAILED' | 'RELEASED' | 'RELEASE_FAILED', required - `resourceId` string, required - `resourceType` 'phone_number' | 'file_system' | 'asset_library', required - `identifier` string, required - `stopRequestedAt` string, date-time - `createdAt` string, date-time, required - `completedAt` string, date-time - `hints` object - RunBlocked - `runId` string, required - `status` 'BLOCKED', required - `provider` string, required - `endpoint` string, required - `reason` string, required - `price` Price, required — User-facing price (markup applied). - `type` string, required - `amount` object, required - `value` number, required - `currency` 'USD', required - `flatFee` object - `value` number, required - `currency` 'USD', required - `period` object - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - `per` union - object - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - number - `unit` 'token' | 'character' | 'second' - `default` union - object - `type` 'PER_CALL', required - `amount` object, required - `value` number, required - `currency` 'USD', required - object - `type` 'PER_RESULT', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `flatFee` object - `value` number, required - `currency` 'USD', required - object - `type` 'METERED', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `per` object, required - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - object - `type` 'PER_UNIT', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `per` number, required - `unit` 'token' | 'character' | 'second', required - `selectors` object[] - `label` string, required - `key` string, required - `in` 'body' | 'queryParam' | 'pathParam' | 'output', required - `variants` object[] - `when` object, required - `price` union, required - object - `type` 'PER_CALL', required - `amount` object, required - … - object - `type` 'PER_RESULT', required - `amount` object, required - … - `flatFee` object - … - object - `type` 'METERED', required - `amount` object, required - … - `per` object, required - … - object - `type` 'PER_UNIT', required - `amount` object, required - … - `per` number, required - `unit` 'token' | 'character' | 'second', required - `label` string - `tiers` object[] - `label` string, required - `when` object, required - `selector` object - `label` string, required - `key` string, required - `in` 'body' | 'queryParam' | 'pathParam' | 'output', required - `price` union, required - object - `type` 'PER_CALL', required - `amount` object, required - … - object - `type` 'PER_RESULT', required - `amount` object, required - … - `flatFee` object - … - object - `type` 'METERED', required - `amount` object, required - … - `per` object, required - … - object - `type` 'PER_UNIT', required - `amount` object, required - … - `per` number, required - `unit` 'token' | 'character' | 'second', required - `notes` string[] - `controls` object[], required - `controlId` string, required - `controlType` string, required - `requiredAmount` number — The gate's pre-flight cost hold/estimate (dollars). - `snapshot` object, required — Dollarized control state snapshot at gate time (same shape as /v1/runs/{runId}/controls). - `createdAt` string, date-time, required - `completedAt` string, date-time, required - `hints` object ## Other responses - `202` — Async run accepted — poll GET /v1/runs/{runId} for results - `400` — Bad request — input failed validation - `401` — Unauthorized — missing or invalid credentials - `402` — Payment required — workspace wallet balance insufficient. (A 402 from this API is ALWAYS about your wallet; an upstream provider's own 402 surfaces as 502.) - `403` — Forbidden — caller has no workspace or no access - `404` — Endpoint not found for provider - `408` — TIMED_OUT — the run exceeded its time budget (run deadline or provider request timeout). Terminal, zero-billed; the body is the full run with status TIMED_OUT. - `500` — Internal server error - `502` — Upstream provider payment/quota failure — the provider returned 402 (its account problem, not your wallet). The body is the full COMPLETED run with the provider's error in providerResponse.error; the run is not charged. --- [API](https://skmtc.net/monid/apis/monid-api.md) · [All operations](https://skmtc.net/monid/apis/monid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/monid/monid-api/versions/164b6b6f2d36/schema)