> ## Documentation Index
> Fetch the complete documentation index at: https://monid.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run

> Execute a data endpoint.

Execute a data endpoint.

For providers which are executed synchronously (e.g. People Data Labs), they return the results immediately; for others (e.g. Apify), the server will return 202 with a run ID and processes the request in the background.

## Request

```text theme={null}
POST /v1/run
```

### Headers

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | `Bearer <api-key>` |
| `Content-Type` | Yes | `application/json` |

### Body

| Field | Type | Required | Description |
| - | - | - | - |
| `provider` | string | Yes | Provider slug (e.g., `"apify"`) |
| `endpoint` | string | Yes | Endpoint path (e.g., `"/apidojo/tweet-scraper"`) |
| `input` | object | No | Input parameters matching the endpoint's input schema (defaults to `{}`) |

### Example Request

```bash curl theme={null}
curl -X POST https://api.monid.ai/v1/run \
  -H "Authorization: Bearer monid_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "apify",
    "endpoint": "/apidojo/tweet-scraper",
    "input": {
      "searchTerms": ["AI"],
      "maxItems": 10
    }
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.monid.ai/v1/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer monid_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    provider: "apify",
    endpoint: "/apidojo/tweet-scraper",
    input: {
      searchTerms: ["AI"],
      maxItems: 10,
    },
  }),
});

const data = await response.json();

if (response.status === 202) {
  // Async provider — poll for results
  const runId = data.runId;
  let result;
  while (true) {
    const poll = await fetch(`https://api.monid.ai/v1/runs/${runId}`, {
      headers: { "Authorization": "Bearer monid_live_..." },
    });
    result = await poll.json();
    if (["COMPLETED", "FAILED", "BLOCKED", "STOPPED", "TIMED_OUT"].includes(result.status)) break;
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
  console.log(result.output);
} else {
  // Sync provider (e.g. PDL) — run completed immediately.
  // The HTTP status mirrors the provider's status (200, 404, 429, ...).
  console.log(data.output);
}
```

```python Python theme={null}
import requests
import time

response = requests.post(
    "https://api.monid.ai/v1/run",
    headers={
        "Authorization": "Bearer monid_live_...",
        "Content-Type": "application/json",
    },
    json={
        "provider": "apify",
        "endpoint": "/apidojo/tweet-scraper",
        "input": {
            "searchTerms": ["AI"],
            "maxItems": 10,
        },
    },
)

data = response.json()

if response.status_code == 202:
    # Async provider — poll for results
    run_id = data["runId"]
    while True:
        result = requests.get(
            f"https://api.monid.ai/v1/runs/{run_id}",
            headers={"Authorization": "Bearer monid_live_..."},
        ).json()
        if result["status"] in ("COMPLETED", "FAILED", "BLOCKED", "STOPPED", "TIMED_OUT"):
            break
        time.sleep(5)
else:
    # Sync provider — run completed immediately.
    # The HTTP status mirrors the provider's status (200, 404, 429, ...).
    result = data

if result["status"] == "FAILED":
    print("Infrastructure error")
elif result["status"] in ("BLOCKED", "STOPPED", "TIMED_OUT"):
    print(f"Run {result['status'].lower()}: {result.get('reason', 'no output returned')}")
elif result.get("providerResponse", {}).get("httpStatus", 200) >= 400:
    print(f"Provider error: HTTP {result['providerResponse']['httpStatus']}")
else:
    print(f"Success: {result.get('output')}")
```

## Response

The response depends on the provider's execution mode:

* **Sync providers** return the completed result immediately — no polling needed. The HTTP status **mirrors the provider's HTTP status**: `200` on success, `404`/`429`/`500` etc. when the provider returned that status (a provider-side `402` is surfaced as `502`). A synchronous run that times out returns `408` (`TIMED_OUT`).
* **Async providers** return `202` with a run ID. Poll [`GET /v1/runs/:runId`](https://monid.ai/docs/api/runs/get) for results.
* A run rejected by a control gate returns `200` with `status: "BLOCKED"` plus `reason` and `controls` fields.

### Completed (Sync)

The run completed immediately. Results are included in the response, and the HTTP status mirrors the provider's status.

| Field | Type | Description |
| - | - | - |
| `runId` | string | Unique run identifier (ULID) |
| `provider` | string | Provider slug |
| `endpoint` | string | Endpoint path |
| `status` | string | Run status: `"COMPLETED"` |
| `output` | any \| null | Provider output data |
| `providerResponse` | object | Provider response metadata |
| `providerResponse.httpStatus` | number | Provider HTTP status code |
| `providerResponse.error` | object \| undefined | Provider error body (non-2xx) |
| `price` | object | Endpoint pricing (`amount` is `{ "value": number, "currency": "USD" }`) |
| `billing` | object \| undefined | Billing breakdown (absent until settled) |
| `billedUnits` | number | Units of the price's billing unit consumed (`0` when nothing billable) |
| `resultCount` | number | Deprecated alias of `billedUnits` |
| `resources` | array \| undefined | Resources provisioned by this run, if any |
| `hints` | object \| undefined | Ready-to-use next-step commands |
| `createdAt` | string | ISO 8601 timestamp |
| `completedAt` | string | ISO 8601 timestamp |

#### Example: Sync Success

```json theme={null}
{
  "runId": "01HXYZ1234567890ABCDEF",
  "provider": "pdl",
  "endpoint": "/person/enrich",
  "status": "COMPLETED",
  "output": {
    "full_name": "John Doe",
    "linkedin_url": "linkedin.com/in/johndoe"
  },
  "providerResponse": {
    "httpStatus": 200
  },
  "price": {
    "type": "PER_CALL",
    "amount": { "value": 0.003, "currency": "USD" }
  },
  "billing": {
    "calculatedCost": { "value": 3000, "unit": "MICRO_DOLLAR", "currency": "USD" },
    "actualCost": { "value": 0, "unit": "MICRO_DOLLAR", "currency": "USD" },
    "reportedCost": { "value": 3000, "unit": "MICRO_DOLLAR", "currency": "USD" }
  },
  "billedUnits": 1,
  "resultCount": 1,
  "createdAt": "2026-03-28T10:30:00.000Z",
  "completedAt": "2026-03-28T10:30:01.000Z"
}
```

#### Example: Sync Provider Error

The run completed, but the provider returned an error. Note `status` is still `"COMPLETED"` — the run lifecycle finished. The response's HTTP status mirrors the provider's status (here: `404 Not Found`).

```json theme={null}
{
  "runId": "01HXYZ1234567890ABCDEF",
  "provider": "pdl",
  "endpoint": "/person/enrich",
  "status": "COMPLETED",
  "output": null,
  "providerResponse": {
    "httpStatus": 404,
    "error": {
      "status": 404,
      "message": "No match found for the given query"
    }
  },
  "price": {
    "type": "PER_CALL",
    "amount": { "value": 0.003, "currency": "USD" }
  },
  "billing": {
    "calculatedCost": { "value": 3000, "unit": "MICRO_DOLLAR", "currency": "USD" },
    "actualCost": { "value": 0, "unit": "MICRO_DOLLAR", "currency": "USD" },
    "reportedCost": { "value": 0, "unit": "MICRO_DOLLAR", "currency": "USD" }
  },
  "billedUnits": 0,
  "resultCount": 0,
  "createdAt": "2026-03-28T10:30:00.000Z",
  "completedAt": "2026-03-28T10:30:01.000Z"
}
```

### 202 Accepted (Async)

The run has been created. Poll [`GET /v1/runs/:runId`](https://monid.ai/docs/api/runs/get) for results.

| Field | Type | Description |
| - | - | - |
| `runId` | string | Unique run identifier (ULID) |
| `provider` | string | Provider slug |
| `endpoint` | string | Endpoint path |
| `status` | string | `"READY"` — the run is queued and about to execute |
| `price` | object | Endpoint pricing |
| `createdAt` | string | ISO 8601 timestamp |

#### Example

```json theme={null}
{
  "runId": "01HXYZ1234567890ABCDEF",
  "provider": "apify",
  "endpoint": "/apidojo/tweet-scraper",
  "status": "READY",
  "price": {
    "type": "PER_CALL",
    "amount": { "value": 0.003, "currency": "USD" }
  },
  "createdAt": "2026-03-28T10:30:00.000Z"
}
```

## Status vs Provider HTTP Status

Every completed run has two independent indicators:

1. **`status`** — the run lifecycle. `"COMPLETED"` means the provider was called and responded. `"FAILED"` means an infrastructure error (our fault). `"BLOCKED"` means a control gate rejected the run before execution. `"STOPPED"` means the run was stopped by request. `"TIMED_OUT"` means the run exceeded its time budget.
2. **`providerResponse.httpStatus`** — the provider's HTTP response code. `200` = data returned. `404` = no match. `429` = rate limited. `500` = provider error.

A run with `status: "COMPLETED"` and `providerResponse.httpStatus: 404` is normal — the run completed, the provider just found no data. Provider errors are not charged.

See [Status vs Provider HTTP Status](https://monid.ai/docs/api/runs/get#status-vs-provider-http-status) for the full reference.

## Polling for Results

For async runs (`202` response), poll [`GET /v1/runs/:runId`](https://monid.ai/docs/api/runs/get) to check status and retrieve results. Most runs complete within 1–120 seconds.

When polling, check two things:

1. **`status`** — wait until a terminal status: `"COMPLETED"`, `"FAILED"`, `"BLOCKED"`, `"STOPPED"`, or `"TIMED_OUT"`
2. **`providerResponse.httpStatus`** — once completed, check if the provider returned a success (2xx) or error (4xx/5xx)

## Next Step

Use [`GET /v1/runs/:runId`](https://monid.ai/docs/api/runs/get) to retrieve run results.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.