Run an operation
One route, POST /v2/run, for every operation. The answer comes back in the same request, with what the call cost.
The request
curl https://api.lobstr.io/v2/run \ -H "Authorization: Bearer $LOBSTR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source": "google_maps", "operation": "reviews/list", "options": { "place": "ChIJc_459AHr9EcRd0ALc7vrjcI" }, "fields": ["rating", "author.name"], "limit": 2 }'
sourcestringrequiredThe site, as the catalog names it: google_maps, leboncoin, x...
operationstringrequiredWhat to do on it, resource/verb: places/search, listings/get, tweets/search...
optionsobjectThe operation's input. Each operation's page lists its options; a wrong one is refused before anything runs, with the option at fault in param.
fieldsstring[]Only these fields of each record, by path (name, address.city). object, id and position always come. Left out: every field.
limitintegerOnly the first 1 to 1,000 records of the answer, for an operation that answers several (a search, a list). The call costs the same, and the next page starts after the whole page, not after the records shown. An operation that answers one record refuses it.
timeout_sintegerThe most seconds to wait. Each operation has its own default and maximum; past them, the call answers 408 timeout and costs nothing.
Idempotency-KeystringheaderMakes a retry safe: 1 to 255 printable characters, a UUID for instance. See Retry safely.
The answer
The envelope first, the records last, in results. A real answer, its cursor and the review id shortened:
{ "object": "run", "id": "run_dp5kejuoabgahbabqw4p77jqi4", "created_at": "2026-11-17T15:05:22.867Z", "livemode": true, "source": "google_maps", "operation": "reviews/list", "version": "1.1.0", "schema_url": "https://api.lobstr.io/v2/catalog/google_maps/reviews/list", "options": { "place": "ChIJc_459AHr9EcRd0ALc7vrjcI", "sort": "newest", "language": "en" }, "fields": [ "rating", "author.name" ], "limit": 2, "status": "succeeded", "count": 2, "has_more": true, "next": { "source": "google_maps", "operation": "reviews/list", "options": { "place": "ChIJc_459AHr9EcRd0ALc7vrjcI", "sort": "newest", "language": "en", "cursor": "gAAAAABq_G0yXBz0j4bINFws…" }, "fields": [ "rating", "author.name" ], "limit": 2 }, "cost": { "credits": 2 }, "balance": { "credits": 9998 }, "duration_ms": 1083, "request_id": "req_mskls2ziorfjfoll32bisidhra", "results": [ { "object": "review", "id": "Ci9DQUlRQUNvZENo…", "position": 1, "rating": { "value": 5, "scale": 5 }, "author": { "name": "Cédric Chapal" } } ] }
idstringThe call's id: GET /v2/runs/{id} finds it again.
versionstringThe operation's version that ran; schema_url is its contract.
optionsobjectWhat ran, the defaults included: how to read the records (their language, their sort).
fields, limitstring[], integerAs asked, or null.
count, has_more, nextinteger, boolean, objectThe records in this answer, whether there are more, and the whole call for the next page: Pagination.
cost, balanceobjectThe credits this call cost, and the credits left: Credits and pricing.
request_idstringAlso in the Request-Id header of every answer, errors included. Quote it when you write to us.
resultsobject[]The records, each with object, id and position, and the fields its operation's page lists.
A call that fails answers an error object instead, and costs nothing: Errors.
Retry safely
Send an Idempotency-Key with a call you may retry, after a timeout or a lost connection. Within 30 days, the same key with the same body answers the first call's answer again, with the header Idempotent-Replayed: true: nothing runs, nothing is charged twice.
- The same key with another body:
409 idempotency_conflict. - The same key while the first call still runs:
409 idempotency_in_flight, retry in 2 seconds. - A call that failed frees its key: the retry runs.
- Each page is its own call: give each one its own key.
Your calls
Every call is kept 90 days, with what was sent and what was answered, records aside:
curl "https://api.lobstr.io/v2/runs?operation=google_maps/reviews/list&status=succeeded" \ -H "Authorization: Bearer $LOBSTR_API_KEY"
limitintegerqueryDefault 201 to 100 calls a page, newest first; next is the following page's path.
operation, status, viastringqueryOnly one operation, succeeded or failed calls, calls made by api, mcp or app.
created_after, created_beforestringqueryDates in UTC, as 2026-11-09T08:00:00Z.
GET /v2/runs/{id} is one call. GET /v2/runs/{id}/response is its whole answer, records included, as long as your plan keeps answers: 7, 45 or 90 days (Credits and pricing).