Runs

List runs and retrieve run status and results.

List Runs

GET /v1/runs

List runs for your workspace with cursor-based pagination.

Headers

Header	Required	Description
Authorization	Yes	Bearer <api-key>

Query Parameters

Parameter	Type	Default	Description
limit	number	10	Maximum runs to return (1-100)
cursor	string	--	Pagination cursor from a previous response

Example Request

curl

curl "https://api.monid.ai/v1/runs?limit=10" \
  -H "Authorization: Bearer monid_live_..."

TypeScript

const response = await fetch("https://api.monid.ai/v1/runs?limit=10", {
  headers: { "Authorization": "Bearer monid_live_..." },
});

const data = await response.json();

Python

import requests

response = requests.get(
    "https://api.monid.ai/v1/runs",
    headers={"Authorization": "Bearer monid_live_..."},
    params={"limit": 10},
)

data = response.json()

200 OK

Field	Type	Description
items	array	List of run summaries
items[].runId	string	Run identifier
items[].caller	string	Caller identifier
items[].provider	string	Provider slug
items[].providerName	string	Provider display name
items[].endpoint	string	Endpoint path
items[].status	string	"READY", "RUNNING", "COMPLETED", or "FAILED"
items[].providerResponse	object | null	Provider response metadata (see Provider Response)
items[].price	object	Endpoint pricing
items[].cost	object | null	Actual cost charged
items[].createdAt	string	ISO 8601 timestamp
items[].startedAt	string | null	When execution started
items[].completedAt	string | null	When execution finished
cursor	string | null	Cursor for the next page. null if last page.

Example Response

{
  "items": [
    {
      "runId": "01HXYZ1234567890ABCDEF",
      "caller": "USER#user_abc123",
      "provider": "apify",
      "providerName": "Apify",
      "endpoint": "/apidojo/tweet-scraper",
      "status": "COMPLETED",
      "providerResponse": {
        "httpStatus": 200
      },
      "price": {
        "type": "PER_CALL",
        "amount": 0.003,
        "currency": "USD"
      },
      "cost": {
        "value": 0.003,
        "currency": "USD"
      },
      "createdAt": "2026-03-28T10:30:00.000Z",
      "startedAt": "2026-03-28T10:30:01.000Z",
      "completedAt": "2026-03-28T10:30:15.000Z"
    }
  ],
  "cursor": null
}

---

Get Run

GET /v1/runs/:runId

Get the status and results of a specific run.

Headers

Header	Required	Description
Authorization	Yes	Bearer <api-key>

Path Parameters

Parameter	Type	Description
runId	string	The run ID to look up

Example Request

curl

curl "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF" \
  -H "Authorization: Bearer monid_live_..."

TypeScript

const response = await fetch(
  "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF",
  {
    headers: { "Authorization": "Bearer monid_live_..." },
  }
);

const data = await response.json();

Python

import requests

response = requests.get(
    "https://api.monid.ai/v1/runs/01HXYZ1234567890ABCDEF",
    headers={"Authorization": "Bearer monid_live_..."},
)

data = response.json()

200 OK

Field	Type	Description
runId	string	Run identifier
caller	string	Caller identifier
provider	string	Provider slug
providerName	string	Provider display name
endpoint	string	Endpoint path
status	string	Run status
input	object	Input parameters
output	any | null	Provider output data (extracted from providerResponse.data)
providerResponse	object | null	Provider response metadata (see Provider Response)
price	object	Endpoint pricing
cost	object | null	Actual cost charged
createdAt	string	ISO 8601 timestamp
startedAt	string | null	When execution started
completedAt	string | null	When execution finished

Example Response

{
  "runId": "01HXYZ1234567890ABCDEF",
  "caller": "USER#user_abc123",
  "provider": "apify",
  "providerName": "Apify",
  "endpoint": "/apidojo/tweet-scraper",
  "status": "COMPLETED",
  "input": {
    "searchTerms": ["AI"],
    "maxItems": 10
  },
  "output": [
    {
      "text": "The future of AI is...",
      "author": "@user123",
      "createdAt": "2026-03-28T09:00:00Z"
    }
  ],
  "providerResponse": {
    "httpStatus": 200
  },
  "price": {
    "type": "PER_CALL",
    "amount": 0.003,
    "currency": "USD"
  },
  "cost": {
    "value": 0.003,
    "currency": "USD"
  },
  "createdAt": "2026-03-28T10:30:00.000Z",
  "startedAt": "2026-03-28T10:30:01.000Z",
  "completedAt": "2026-03-28T10:30:15.000Z"
}

Caching

Terminal runs (COMPLETED or FAILED) include a Cache-Control: max-age=300 header (5 minutes). Running runs are not cached.

Status vs Provider HTTP Status

Every run has two independent indicators:

1. status -- the run lifecycle status. Did the run itself complete?
2. providerResponse.httpStatus -- the provider's HTTP response code. Did the data provider return good data?

Run Status

Status	Meaning
READY	Queued, waiting to start
RUNNING	Actively executing
COMPLETED	Run finished -- the provider was called and responded
FAILED	Infrastructure failure -- pipeline crash, timeout, or internal error (our fault)

COMPLETED means the run lifecycle finished and the provider was called. It does not mean the data request succeeded. The provider may have returned a successful response (HTTP 2xx) or an error (HTTP 4xx/5xx).

Provider HTTP Status

When a run is COMPLETED, check providerResponse.httpStatus to determine result quality:

HTTP Status	Meaning
200	Success -- output contains results
400	Bad request -- invalid parameters sent to provider
404	Not found -- no match for the query
429	Rate limited -- provider throttled the request
500	Provider error -- the provider's service failed

Provider Response

The providerResponse object is included in both list and detail responses:

Field	Type	Description
httpStatus	number | undefined	HTTP status code from the provider (200, 400, 404, 429, 500, etc.)
error	object | undefined	Error body from the provider (on non-2xx responses)

TIP

The output field contains the provider's successful response data. For provider errors (non-2xx), output will be null and the error details are in providerResponse.error.

Success Example

{
  "runId": "01HXYZ...",
  "status": "COMPLETED",
  "output": [{ "name": "John Doe", "email": "john@example.com" }],
  "providerResponse": {
    "httpStatus": 200
  },
  "cost": {
    "value": 0.003,
    "currency": "USD"
  }
}

Provider Error Example

{
  "runId": "01HXYZ...",
  "status": "COMPLETED",
  "output": null,
  "providerResponse": {
    "httpStatus": 404,
    "error": {
      "status": 404,
      "message": "No match found for the given query"
    }
  },
  "cost": {
    "value": 0,
    "currency": "USD"
  }
}

Provider errors are not charged -- cost.value will be 0.