List your research jobs
Returns the caller's research jobs, newest first, alongside the daily run budget line. Each entry carries the job's status, the Apify actor that ran it, and `costCents` — the run cost Apify reported against the caller's own Apify account. The figure is informational: Putty does not bill for research runs and does not mark up the cost.
Returns the caller's research jobs, newest first, alongside the daily run budget line. Each entry carries the job's status, the Apify actor that ran it, and costCents — the run cost Apify reported against the caller's own Apify account. The figure is informational: Putty does not bill for research runs and does not mark up the cost.
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/research/jobs"{ "jobs": [ { "id": "string", "tool": "string", "status": {}, "actorId": "string", "apifyRunId": "string", "costCents": 0, "costUsd": "string", "itemCount": 0, "truncated": true, "items": [ { "url": "string", "timestamp": "string", "author": "string", "likes": 0, "comments": 0, "shares": 0 } ], "content": "string", "fullDataUrl": "string", "expiresAt": "string", "createdAt": "string", "error": "string" } ], "runsUsedToday": 0, "runsPerUserPerDay": 0}Read the research caps GET
Returns the caps the research tools enforce server-side, so a client does not have to hard-code them: how many search results, crawl pages, and posts a call may ask for, and how many bytes of scraped text come back in one result. A request above a cap is clamped, not rejected — except a value that is not a positive integer, which is a malformed call.
Start a research run POST
Starts one research run and returns the stored job. The run is asynchronous: this call starts it, and `GET /research/jobs/{id}` reports whether it has finished and what it found. The body's `tool` selects what runs, and the fields it accepts depend on that choice — a search takes a `query`, a crawl takes a `url`, a social read takes a `platform`. A field the chosen tool does not take is refused as a validation error. The run is charged against the caller's own Apify account, so a caller with no stored key is refused with `integration_required` before anything is started and nothing is spent. A caller over their daily run allowance is refused with 429 and a `Retry-After`; that refusal costs no run either. The response's `job.id` is what the Apify callback is signed against and what to poll. The caller's own id and the arguments the run received are not in the response.