Documentation menu

← Account

API reference

List requests

GET/v1/usage/request

Lists requests to /v1 endpoints, newest first, with each one's status, credits and credential.

GET /v1/me is not included, nor are requests refused for a missing or invalid credential.

Parameters

query

request_idstring | null
Only the request with this id, from the request-id response header.
routestring[]
Only requests to these endpoints, as path templates such as /v1/parcel. Repeat for several.
keystring | null
Only requests made with this API key id.
userstring | null
Only requests made by this user id, directly or through an OAuth client.
clientstring | null
Only requests made through this OAuth client id.
actor_method"session" | "api_key" | "oauth" | "mcp"[]
Only requests authenticated this way. One of session, api_key, oauth or mcp. Repeat for several.
errorboolean | null
true for only failed requests (status 400 or above), false for only successful ones.
min_occurredstring | null
Only requests received at or after this time, in ISO 8601.
max_occurredstring | null
Only requests received before this time, in ISO 8601.
cursorstring | null
A cursor for pagination: the next_cursor from the previous page.
sizeinteger | null
Number of results per page, between 1 and 200. Defaults to 20.

Responses

200
Collection_Request_
A page of requests.
401
ProblemDetail
credential_missing, credential_invalid or credential_expired. The request has no valid credential.
403
ProblemDetail
api_key_not_accepted. The request used an API key. This endpoint accepts a console session or an MCP token.
422
ProblemDetail
parameter_invalid, id_malformed or a cursor code. A parameter is missing or invalid. errors lists each one.
429
ProblemDetail
rate_limited. Too many requests. Retry after the Retry-After interval. Nothing is charged.

Credits

Free.

Example request

curl -X GET 'https://api.placestack.com/v1/usage/request' \
  -H "Authorization: Bearer $PLACESTACK_API_KEY"

Example response

{
  "object": "list",
  "data": [
    {
      "object": "request",
      "request_id": "req_7872540bd07601eae287aa02",
      "occurred_at": "2026-09-13T12:00:00Z",
      "method": "GET",
      "route": "/v1/parcel",
      "status": 1,
      "credits": 1,
      "free_reason": "cached",
      "duration_ms": 1,
      "actor": {
        "kind": "user",
        "method": "session",
        "name": "Production",
        "key": "0192f3a4-7d8e-7f90-b123-456789abcdef",
        "user": "0192f3a4-6c7d-7e8f-a012-3456789abcde",
        "client": "placestack-console"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJrIjoiMjAyNi0xMC0wMSIsInQiOjQyfQ",
  "suppressed": 0,
  "total": {
    "value": 1,
    "relation": "eq"
  }
}