Runs
Start a run, wait for it or let it run in the background, and fetch the results as JSON or CSV.
A run is one execution of one tool with one input. You start it with POST /api/v1/tools/{toolId}/runs; the request body is the tool's input as JSON. The input fields of every tool are in the tool reference and in the live catalog at GET /api/v1/tools.
Sync runs (default)
Without extra parameters the request waits for the run and answers 200 with the run and its results:
curl -X POST "https://pullwire.dev/api/v1/tools/youtube-transcripts/runs" \
-H "x-api-key: $PULLWIRE_API_KEY" -H "content-type: application/json" \
-d '{"videos": ["jNQXAC9IVRw"]}'A sync run gets 25 seconds. If the tool is not done by then, it stops: you get the results it collected so far, they are charged and saved, and run.error says that the run stopped at the deadline. For bigger jobs use an async run.
Async runs
Add ?async=1 to start the run in the background. The request answers right away with 202 and the run:
curl -X POST "https://pullwire.dev/api/v1/tools/youtube-transcripts/runs?async=1" \
-H "x-api-key: $PULLWIRE_API_KEY" -H "content-type: application/json" \
-d '{"videos": ["jNQXAC9IVRw", "dQw4w9WgXcQ"]}'An async run gets up to 50 seconds. Check its status with the run ID until it is succeeded or failed:
curl "https://pullwire.dev/api/v1/runs/$RUN_ID" -H "x-api-key: $PULLWIRE_API_KEY"Run status
| Status | Meaning |
|---|---|
queued | The run was created and is waiting to start (async runs). |
running | Credits are reserved and the tool is working. |
succeeded | The run finished. resultsCount can be 0 if nothing matched your input. If error is set, the results are partial: the run stopped early (for example at the deadline) or some items could not be fetched (for example BLOCKED). Everything in the results was charged and saved. |
failed | The run could not start (for example not enough credits), crashed, or ended without a single result because the target site could not be reached (for example every request was BLOCKED). error says why. A run that simply found nothing is succeeded with 0 results, not failed. Results produced before a crash were charged and saved. |
Other useful fields on a run: resultsCount, creditsUsed, durationMs, createdAt and updatedAt.
How many results
Most tools accept a maxResults field. If you leave it out, a run returns at most 20 results. You can ask for up to 200 results per run; for more, start several runs. Credits are reserved for maxResults results before the run starts, so a high value needs enough balance even if fewer results come back (see Credits).
Fetch results
Results of a finished run stay available. Fetch them as JSON:
curl "https://pullwire.dev/api/v1/runs/$RUN_ID/results" -H "x-api-key: $PULLWIRE_API_KEY"or as CSV, for a spreadsheet:
curl "https://pullwire.dev/api/v1/runs/$RUN_ID/results?format=csv" \
-H "x-api-key: $PULLWIRE_API_KEY" -o results.csvFor an Excel file, use ?format=xlsx instead (same headers, -o results.xlsx).
Large runs are also saved as ready-made files you can download for 30 days, see Datasets.
You can only read runs of your own organization; any other run ID answers 404 NOT_FOUND.
When a sync run crashes
If a sync run fails after it already produced results, the API answers 500 INTERNAL_ERROR and includes the runId in the error body. The results produced before the crash were charged, and you can still fetch them with GET /api/v1/runs/{runId}/results.