> ## 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.

# monid run

> Execute a data endpoint and retrieve results.

Execute a data endpoint and retrieve results.

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.

## Usage

```bash theme={null}
monid run -p <provider> -e <endpoint> -i <input> [--wait [timeout]] [-o <file>] [--json]
```

## Flags

| Flag                        | Type    | Required | Description                                                     |
| --------------------------- | ------- | -------- | --------------------------------------------------------------- |
| `-p, --provider <provider>` | string  | Yes      | Provider slug                                                   |
| `-e, --endpoint <endpoint>` | string  | Yes      | Endpoint path                                                   |
| `-i, --input <input>`       | string  | Yes      | Input as inline JSON or `@path/to/file.json`                    |
| `-f, --input-file <path>`   | string  | No       | Read input from a JSON file (alternative to `-i @file`)         |
| `-w, --wait [timeout]`      | number  | No       | Wait for completion. Optional timeout in seconds (default: 300) |
| `-o, --output <path>`       | string  | No       | Save output to a file                                           |
| `-j, --json`                | boolean | No       | Output raw JSON                                                 |

## Examples

### Run and poll separately (recommended)

```bash theme={null}
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}'
# → Run ID: 01HXYZ...

monid runs get -r 01HXYZ... -o tweets.json
```

### Run with wait

```bash theme={null}
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":10}' \
  --wait -o tweets.json
```

### Input from file

```bash theme={null}
monid run -p apify -e /damilo/google-maps-scraper \
  -i @params.json -o results.json
```

### With custom timeout

```bash theme={null}
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["AI"],"maxItems":50}' \
  --wait 120 -o tweets.json
```

## Output

### Sync providers

For sync providers, the result is returned immediately — no polling needed:

```text theme={null}
Run ID:    01HXYZ...
Status:    COMPLETED
Response:  HTTP 200
Provider:  pdl
Endpoint:  /person/enrich
Price:     $0.003/call
Cost:      $0.003
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:01Z

{
  "full_name": "John Doe",
  "linkedin_url": "linkedin.com/in/johndoe"
}
```

### Async providers

For async providers, the run starts in the background. Poll with `monid runs get` or use `--wait`:

```text theme={null}
Run started
  Run ID:   01HXYZ...
  Provider: apify
  Endpoint: /apidojo/tweet-scraper
  Status:   RUNNING
  Price:    $0.003/call

Poll with: monid runs get -r 01HXYZ...
```

With `--wait`, the CLI polls automatically until the run completes:

```text theme={null}
Run ID:    01HXYZ...
Status:    COMPLETED
Response:  HTTP 200
Provider:  apify
Endpoint:  /apidojo/tweet-scraper
Price:     $0.003/call
Cost:      $0.003
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:15Z

Results saved to tweets.json
```

### Provider errors

If the provider returned an error, the run still shows `Status: COMPLETED` (the run itself finished) but the `Response` line shows the provider's HTTP status:

```text theme={null}
Run ID:    01HXYZ...
Status:    COMPLETED
Response:  HTTP 404 — No match found for the given query
Provider:  pdl
Endpoint:  /person/enrich
Price:     $0.003/call
Cost:      $0.00
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:01Z
```

### Infrastructure errors

If Monid itself failed to execute the run, the status is `FAILED`:

```text theme={null}
Run ID:    01HXYZ...
Status:    FAILED
Provider:  apify
Endpoint:  /apidojo/tweet-scraper
Price:     $0.003/call
Cost:      $0.00
Created:   2026-03-28T10:30:00Z
Done:      2026-03-28T10:30:02Z

Error: An internal error occurred while processing this run.
```

## Status vs Provider HTTP Status

Every completed run has two independent indicators:

| Field        | What it tells you             | Example                            |
| ------------ | ----------------------------- | ---------------------------------- |
| **Status**   | Did the run complete?         | `COMPLETED`, `FAILED`              |
| **Response** | What did the provider return? | `HTTP 200`, `HTTP 404`, `HTTP 500` |

* `Status: COMPLETED` + `Response: HTTP 200` = success, data returned
* `Status: COMPLETED` + `Response: HTTP 404` = run finished, but provider found no data
* `Status: COMPLETED` + `Response: HTTP 500` = run finished, but provider had an error
* `Status: FAILED` = infrastructure error (our fault), no provider response

Provider errors (non-2xx responses) are not charged.

## Next Steps

* [`monid runs get`](/cli/runs/get) — Check run status and retrieve results
* [`monid inspect`](/cli/inspect) — Verify input schema before running