monid run

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

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)

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

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

Input from file

monid run -p apify -e /damilo/google-maps-scraper \
  -i @params.json -o results.json

With custom timeout

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:

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:

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:

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:

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:

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 -- Check run status and retrieve results
• monid inspect -- Verify input schema before running