---
title: "List requests"
method: GET
path: "/usage/request"
tags: ["usage"]
---

# List requests

`GET /usage/request`

## Request

- Base URL: `http://localhost:3030`
- URL: `http://localhost:3030/usage/request`
- Auth: HTTP bearer

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.

## Query parameters

- `request_id` string, nullable: Only the request with this id, from the `request-id` response header.
- `route` string[]: Only requests to these endpoints, as path templates such as `/v1/parcel`. Repeat for several.
- `key` string, nullable: Only requests made with this API key id.
- `user` string, nullable: Only requests made by this user id, directly or through an OAuth client.
- `client` string, nullable: Only requests made through this OAuth client id.
- `actor_method` string[]: Only requests authenticated this way. One of `session`, `api_key`, `oauth` or `mcp`. Repeat for several.
- `error` boolean, nullable: `true` for only failed requests (status `400` or above), `false` for only successful ones.
- `min_occurred` string, date-time, nullable: Only requests received at or after this time, in ISO 8601.
- `max_occurred` string, date-time, nullable: Only requests received before this time, in ISO 8601.
- `cursor` string, nullable: A cursor for pagination: the `next_cursor` from the previous page.
- `size` integer, nullable: Number of results per page, between 1 and 200. Defaults to 20.

## Response `200`

A page of requests.

- CollectionRequest
  - `object` 'list', required: The object's type. Always `list`.
  - `data` Request[], required: The results on this page.
    - `object` 'request', required: The object's type. Always `request`.
    - `request_id` string, nullable, required: The request's id, also sent as the `request-id` response header. Include it when contacting support about a request.
    - `occurred_at` string, date-time, required: Time at which the request was received.
    - `method` string, required: The HTTP method, such as `GET`.
    - `route` string, required: The endpoint, as its path template, such as `/v1/parcel/{parcel_id}`. Path values and query strings are not stored.
    - `status` integer, required: The response's HTTP status.
    - `credits` integer, required: Credits charged.
    - `free_reason` 'cached' | 'not_found' | 'not_covered' | 'empty' | 'error' | 'included' | 'seat', nullable, required: Why no credits were charged. One of `cached` (a repeat within a day), `not_found`, `not_covered`, `empty`, `error`, `included` (a read that is never charged) or `seat` (a read in Explorer). Null when credits were charged.
    - `duration_ms` integer, nullable, required: Time to respond, in milliseconds. Null when not recorded.
    - `actor` RequestActor, required: The credential that made a request.
      - `kind` 'user' | 'machine', required: Whether a person or a machine credential made the request. One of `user` or `machine`.
      - `method` 'session' | 'api_key' | 'oauth' | 'mcp', required: How the request was authenticated. One of `session`, `api_key`, `oauth` or `mcp`.
      - `name` string, nullable, required: The API key's name, the user's email address or the OAuth client's name, for display. Null when there is none.
      - `key` string, nullable, required: The API key's id. Null when no API key was used.
      - `user` string, nullable, required: The user's id. Null for a machine credential.
      - `client` string, nullable, required: The OAuth client's id. Null when no OAuth client was used.
  - `has_more` boolean, required: Whether there are more results after this page.
  - `next_cursor` string, nullable, required: The cursor for the next page. Send it as `cursor`. Null on the last page.
  - `suppressed` integer, required: The number of matching results withheld because the plan does not include them.
  - `total` Total, required: The number of matching results.
    - `value` integer, required: The number of matching results.
    - `relation` 'eq' | 'gte', required: One of `eq` (exact) or `gte` (at least `value`). Counts above 10,000 are `gte`.

## Other responses

- `401`: `credential_missing`, `credential_invalid` or `credential_expired`. The request has no valid credential.
- `403`: `api_key_not_accepted`. The request used an API key. This endpoint accepts a console session or an MCP token.
- `422`: `parameter_invalid`, `id_malformed` or a cursor code. A parameter is missing or invalid. `errors` lists each one.

---

[API](https://skmtc.dev/placestack/apis/placestack-api.md) · [All operations](https://skmtc.dev/placestack/apis/placestack-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placestack/apis/placestack-api/revisions/0ccdf0882668?raw)