Monid Runs API
The Runs API from Monid — 5 operation(s) for runs.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/monid-runs-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Monid Runs API
version: 0.1.0
description: Agentic payment platform for data — agents discover and buy data on demand. Authenticated `/v1/*` routes accept a Monid API key or Clerk JWT as a Bearer token. All errors return `{ code, message }`. List endpoints use cursor pagination; consult each operation schema for its last-page cursor encoding.
servers:
- url: https://api.monid.ai
description: Production
- url: https://monid.ai
description: Public registry alias (public/v1 only)
tags:
- name: Runs
paths:
/v1/run:
post:
tags:
- Runs
summary: Start an endpoint run
description: 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.
security:
- Bearer: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunRequest'
responses:
'200':
description: 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.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/RunCompleted'
- $ref: '#/components/schemas/RunBlocked'
'202':
description: Async run accepted — poll GET /v1/runs/{runId} for results
content:
application/json:
schema:
$ref: '#/components/schemas/RunAccepted'
'400':
description: Bad request — input failed validation
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized — missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'402':
description: 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.)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — caller has no workspace or no access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Endpoint not found for provider
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'408':
description: 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.
content:
application/json:
schema:
$ref: '#/components/schemas/RunCompleted'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: 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.
content:
application/json:
schema:
$ref: '#/components/schemas/RunCompleted'
/v1/runs:
get:
tags:
- Runs
summary: List runs
description: Cursor-paginated list of the workspace's runs, newest first. Optional `status` filter.
security:
- Bearer: []
parameters:
- schema:
type: integer
exclusiveMinimum: 0
maximum: 100
description: Max items per page (server-side cap applies).
example: 20
required: false
description: Max items per page (server-side cap applies).
name: limit
in: query
- schema:
type: string
description: Cursor returned by the previous page.
required: false
description: Cursor returned by the previous page.
name: cursor
in: query
- schema:
type: string
enum:
- READY
- RUNNING
- STOPPING
- COMPLETED
- FAILED
- BLOCKED
- STOPPED
- TIMED_OUT
description: Filter runs by lifecycle status.
required: false
description: Filter runs by lifecycle status.
name: status
in: query
responses:
'200':
description: Runs page
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/RunListItem'
cursor:
type: string
description: Opaque cursor for the next page. Absent on the last page.
required:
- items
'400':
description: Bad request — input failed validation
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized — missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — caller has no workspace or no access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/runs/{runId}:
get:
tags:
- Runs
summary: Get a run
description: Poll run status and retrieve results. Terminal runs include the resolved provider `output`.
security:
- Bearer: []
parameters:
- schema:
type: string
description: Run identifier (ULID).
example: 01JGXYZABCDEFGHJKMNPQRSTVW
required: true
description: Run identifier (ULID).
name: runId
in: path
responses:
'200':
description: The run (with output when terminal)
content:
application/json:
schema:
$ref: '#/components/schemas/Run'
'401':
description: Unauthorized — missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — caller has no workspace or no access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Run not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/runs/{runId}/controls:
get:
tags:
- Runs
summary: List a run's control records
description: All control junction records for a run — budget controls (HELD/SETTLED/RELEASED/BLOCKED) and run cap controls (BLOCKED).
security:
- Bearer: []
parameters:
- schema:
type: string
description: Run identifier (ULID).
example: 01JGXYZABCDEFGHJKMNPQRSTVW
required: true
description: Run identifier (ULID).
name: runId
in: path
- schema:
type: string
description: Max items per page (server-side cap applies).
example: '20'
required: false
description: Max items per page (server-side cap applies).
name: limit
in: query
- schema:
type: string
description: Cursor returned by the previous page.
required: false
description: Cursor returned by the previous page.
name: cursor
in: query
responses:
'200':
description: Control records page
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/ControlRun'
cursor:
type:
- string
- 'null'
description: Opaque cursor for the next page; null on the last page.
required:
- items
- cursor
'401':
description: Unauthorized — missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — caller has no workspace or no access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Run not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/runs/{runId}/stop:
post:
tags:
- Runs
summary: Stop a run
description: Request the platform stop a non-terminal, stoppable run. The stop is asynchronous — poll GET /v1/runs/{runId} to observe the terminal STOPPED status.
security:
- Bearer: []
parameters:
- schema:
type: string
description: Run identifier (ULID).
example: 01JGXYZABCDEFGHJKMNPQRSTVW
required: true
description: Run identifier (ULID).
name: runId
in: path
responses:
'202':
description: Stop requested (asynchronous)
content:
application/json:
schema:
$ref: '#/components/schemas/RunStopAccepted'
'401':
description: Unauthorized — missing or invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden — caller has no workspace or no access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Run not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Run is terminal, not stoppable, or no longer running
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
RunStopAccepted:
type: object
properties:
runId:
type: string
status:
type: string
enum:
- STOPPING
message:
type: string
required:
- runId
- status
- message
Error:
type: object
properties:
code:
type: integer
description: HTTP status code, duplicated in the body.
example: 400
message:
type: string
description: Human-readable error description.
example: Bad Request
required:
- code
- message
Cost:
type: object
properties:
value:
type: number
currency:
type: string
enum:
- USD
required:
- value
- currency
RunListItem:
type: object
properties:
runId:
type: string
description: Run identifier (ULID).
example: 01JGXYZABCDEFGHJKMNPQRSTVW
caller:
type: string
description: Prefixed polymorphic caller id (e.g. `USER#<userId>`).
provider:
type: string
providerName:
type: string
endpoint:
type: string
status:
type: string
enum:
- READY
- RUNNING
- STOPPING
- COMPLETED
- FAILED
- BLOCKED
- STOPPED
- TIMED_OUT
stoppable:
type: boolean
providerResponse:
$ref: '#/components/schemas/ProviderResponse'
price:
$ref: '#/components/schemas/Price'
cost:
$ref: '#/components/schemas/Cost'
resultCount:
type: integer
minimum: 0
billedUnits:
type: integer
minimum: 0
createdAt:
type: string
format: date-time
startedAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
required:
- runId
- caller
- provider
- endpoint
- status
- price
- createdAt
ProviderResponse:
type: object
properties:
httpStatus:
type: integer
description: HTTP status from the provider (e.g. 200, 400, 404, 429, 500).
example: 200
error:
description: Provider error body, passed through faithfully on failure.
metadata:
type: object
additionalProperties: {}
description: Provider-specific debug metadata lifted from the raw response.
Price:
type: object
properties:
type:
type: string
amount:
anyOf:
- type: object
properties:
value:
type: number
currency:
type: string
enum:
- USD
required:
- value
- currency
- type: object
properties:
type:
type: string
enum:
- PER_TOKEN
amount:
type: object
properties:
value:
type: number
currency:
type: string
enum:
- USD
required:
- value
- currency
per:
type: number
unit:
type: string
enum:
- token
- character
required:
- type
- amount
- per
- unit
flatFee:
type: object
properties:
value:
type: number
currency:
type: string
enum:
- USD
required:
- value
- currency
period:
type: object
properties:
unit:
type: string
enum:
- MINUTE
- DAY
- MONTH
count:
type: integer
exclusiveMinimum: 0
required:
- unit
- count
per:
type: object
properties:
unit:
type: string
enum:
- MINUTE
- DAY
- MONTH
count:
type: integer
exclusiveMinimum: 0
required:
- unit
- count
selectors:
type: array
items:
type: object
properties:
label:
type: string
key:
type: string
in:
type: string
enum:
- body
- queryParam
- pathParam
required:
- label
- key
- in
variants:
type: array
items:
type: object
properties:
when:
type: object
additionalProperties:
anyOf:
- type: string
- type: number
amount:
anyOf:
- type: object
properties:
value:
type: number
currency:
type: string
enum:
- USD
required:
- value
- currency
- type: object
properties:
type:
type: string
enum:
- PER_TOKEN
amount:
type: object
properties:
value:
type: number
currency:
type: string
enum:
- USD
required:
- value
- currency
per:
type: number
unit:
type: string
enum:
- token
- character
required:
- type
- amount
- per
- unit
label:
type: string
required:
- when
- amount
notes:
type: array
items:
type: string
required:
- type
- amount
description: User-facing price (markup applied).
RunAccepted:
type: object
properties:
runId:
type: string
provider:
type: string
endpoint:
type: string
status:
type: string
enum:
- READY
- RUNNING
- STOPPING
- COMPLETED
- FAILED
- BLOCKED
- STOPPED
- TIMED_OUT
price:
$ref: '#/components/schemas/Price'
createdAt:
type: string
format: date-time
hints:
type: object
additionalProperties:
anyOf:
- type: string
- type: object
properties:
kind:
type: string
enum:
- command
- discover
- inspect
- run
- getRun
- stop
- releaseResource
command:
type: string
query:
type: string
provider:
type: string
endpoint:
type: string
runId:
type: string
resourceId:
type: string
comment:
type: string
required:
- kind
required:
- runId
- provider
- endpoint
- status
- price
- createdAt
Run:
type: object
properties:
runId:
type: string
description: Run identifier (ULID).
example: 01JGXYZABCDEFGHJKMNPQRSTVW
caller:
type: string
description: Prefixed polymorphic caller id (e.g. `USER#<userId>`).
provider:
type: string
providerName:
type: string
endpoint:
type: string
status:
type: string
enum:
- READY
- RUNNING
- STOPPING
- COMPLETED
- FAILED
- BLOCKED
- STOPPED
- TIMED_OUT
description: Run lifecycle status. COMPLETED means the provider responded (any HTTP status); FAILED means an infrastructure failure.
stoppable:
type: boolean
reason:
type: string
controls:
type: array
items:
type: object
additionalProperties: {}
input:
type: object
properties:
body:
type: object
additionalProperties: {}
description: Request body fields.
queryParams:
type: object
additionalProperties: {}
description: URL query string parameters.
pathParams:
type: object
additionalProperties: {}
description: URL path placeholder substitutions (e.g. {id} in `/users/{id}`).
additionalProperties: false
description: Composite endpoint input — body + URL query + URL path. All sub-fields optional.
output:
description: Provider output data (terminal runs only; may be null).
providerResponse:
$ref: '#/components/schemas/ProviderResponse'
price:
$ref: '#/components/schemas/Price'
cost:
$ref: '#/components/schemas/Cost'
resultCount:
type: integer
minimum: 0
billedUnits:
type: integer
minimum: 0
resources:
type: array
items:
type: object
properties:
action:
type: string
enum:
- PROVISIONED
- PROVISION_FAILED
- RELEASED
- RELEASE_FAILED
resourceId:
type: string
minLength: 1
resourceType:
type: string
enum:
- phone_number
identifier:
type: string
minLength: 1
required:
- action
- resourceId
- resourceType
- identifier
createdAt:
type: string
format: date-time
startedAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
hints:
type: object
additionalProperties:
anyOf:
- type: string
- type: object
properties:
kind:
type: string
enum:
- command
- discover
- inspect
- run
- getRun
- stop
- releaseResource
command:
type: string
query:
type: string
provider:
type: string
endpoint:
type: string
runId:
type: string
resourceId:
type: string
comment:
type: string
required:
- kind
required:
- runId
- caller
- provider
- endpoint
- status
- input
- price
- createdAt
RunBlocked:
type: object
properties:
runId:
type: string
status:
type: string
enum:
- BLOCKED
provider:
type: string
endpoint:
type: string
reason:
type: string
price:
$ref: '#/components/schemas/Price'
controls:
type: array
items:
type: object
properties:
controlId:
type: string
controlType:
type: string
requiredAmount:
type: number
description: The gate's pre-flight cost hold/estimate (dollars).
snapshot:
type: object
additionalProperties: {}
description: Dollarized control state snapshot at gate time (same shape as /v1/runs/{runId}/controls).
required:
- controlId
- controlType
- snapshot
createdAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
hints:
type: object
additionalProperties:
anyOf:
- type: string
- type: object
properties:
kind:
type: string
enum:
- command
- discover
- inspect
- run
- getRun
- stop
- releaseResource
command:
type: string
query:
type: string
provider:
type: string
endpoint:
type: string
runId:
type: string
resourceId:
type: string
comment:
type: string
required:
- kind
required:
- runId
- status
- provider
- endpoint
- reason
- price
- controls
- createdAt
- completedAt
ControlRun:
type: object
additionalProperties: {}
RunRequest:
type: object
properties:
provider:
type: string
minLength: 1
description: Provider slug.
example: exa
endpoint:
type: string
minLength: 1
description: Endpoint path within the provider.
example: search
input:
type: object
properties:
body:
type: object
additionalProperties: {}
description: Request body fields.
queryParams:
type: object
additionalProperties: {}
description: URL query string parameters.
pathParams:
type: object
additionalProperties: {}
description: URL path placeholder substitutions (e.g. {id} in `/users/{id}`).
additionalProperties: false
description: Composite endpoint input — body + URL query + URL path. All sub-fields optional.
required:
- provider
- endpoint
additionalProperties: false
RunCompleted:
type: object
properties:
runId:
type: string
provider:
type: string
endpoint:
type: string
status:
type: string
enum:
- READY
- RUNNING
- STOPPING
- COMPLETED
- FAILED
- BLOCKED
- STOPPED
- TIMED_OUT
output:
description: Provider output data (may be null).
providerResponse:
$ref: '#/components/schemas/ProviderResponse'
price:
$ref: '#/components/schemas/Price'
billing:
type: object
properties:
calculatedCost:
type: object
properties:
currency:
type: string
enum:
- USD
value:
type: integer
minimum: 0
unit:
type: string
enum:
- MICRO_DOLLAR
- CENT
- DOLLAR
required:
- currency
- value
- unit
actualCost:
type: object
properties:
currency:
type: string
enum:
- USD
value:
type: integer
minimum: 0
unit:
type: string
enum:
- MICRO_DOLLAR
- CENT
- DOLLAR
required:
- currency
- value
- unit
reportedCost:
type: object
properties:
currency:
type: string
enum:
- USD
value:
type: integer
minimum: 0
unit:
type: string
enum:
- MICRO_DOLLAR
- CENT
- DOLLAR
required:
- currency
- value
- unit
required:
- calculatedCost
- actualCost
- reportedCost
resultCount:
type: integer
minimum: 0
billedUnits:
type: integer
minimum: 0
resources:
type: array
items:
type: object
properties:
action:
type: string
enum:
- PROVISIONED
- PROVISION_FAILED
- RELEASED
- RELEASE_FAILED
resourceId:
type: string
minLength: 1
resourceType:
type: string
enum:
- phone_number
identifier:
type: string
minLength: 1
required:
- action
- resourceId
- resourceType
- identifier
stopRequestedAt:
type: string
format: date-time
createdAt:
type: string
format: date-time
completedAt:
type: string
format: date-time
hints:
type: object
additionalProperties:
anyOf:
- type: string
- type: object
properties:
kind:
type: string
enum:
- command
- discover
- inspect
- run
- getRun
- stop
- releaseResource
command:
type: string
query:
type: string
provider:
type: string
endpoint:
type: string
runId:
type: string
resourceId:
type: string
comment:
type: string
required:
- kind
required:
- runId
- provider
- endpoint
- status
- providerResponse
- price
- createdAt
securitySchemes:
Bearer:
type: http
scheme: bearer
description: 'Monid API key (`Authorization: Bearer mk_...`) or Clerk-issued JWT.'