Skip to content
Concepts

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
  }'
sourcestringrequired

The site, as the catalog names it: google_maps, leboncoin, x...

operationstringrequired

What to do on it, resource/verb: places/search, listings/get, tweets/search...

optionsobject

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

limitinteger

Only 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_sinteger

The most seconds to wait. Each operation has its own default and maximum; past them, the call answers 408 timeout and costs nothing.

Idempotency-Keystringheader

Makes 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"
      }
    }
  ]
}
idstring

The call's id: GET /v2/runs/{id} finds it again.

versionstring

The operation's version that ran; schema_url is its contract.

optionsobject

What ran, the defaults included: how to read the records (their language, their sort).

fields, limitstring[], integer

As asked, or null.

count, has_more, nextinteger, boolean, object

The records in this answer, whether there are more, and the whole call for the next page: Pagination.

cost, balanceobject

The credits this call cost, and the credits left: Credits and pricing.

request_idstring

Also 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 20

1 to 100 calls a page, newest first; next is the following page's path.

operation, status, viastringquery

Only one operation, succeeded or failed calls, calls made by api, mcp or app.

created_after, created_beforestringquery

Dates 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).