Usage API.

The numbers on your Usage and Logs pages, for an agent that wants to check its own spend.

GET https://metasearch.sh/api/v1/usage
GET https://metasearch.sh/api/v1/requests
GET https://metasearch.sh/api/v1/requests/{id}
Authorization: Bearer ms_live_…

All three take any API key of the organisation and read the whole organisation, not only that key's calls. Amounts come twice: in dollars (charged_usd) and as whole micro-dollars (charged_micros, 1 µ$ = $0.000001), as on Billing, and times are UTC.

Usage totals#

GET /api/v1/usagereturns the organisation's requests, failures and charges over a range of whole UTC days, today included: a series by day (by hour for a range of two days or less), the totals and the same totals for the period before, and a breakdown per key, per engine and per mode with p50 and p95 latency.

parameter	meaning
days	1 to 90, default 30.
from, to	UTC days as `YYYY-MM-DD`, both included, at most 400 days apart. They replace `days`.
key_id	Only the calls made with this key.

Request log#

GET /api/v1/requests lists calls newest first, with the same filters as the Logs page. Each item has the request id, time, mode, status, the query (when the organisation stores queries and the retention period has not passed), the engines asked and the engines that served, the result count, the amount reserved and charged, the latency and the HTTP status.

parameter	meaning
mode	One mode, for example `news`.
provider	One engine name.
status	`ok`, `empty` (no results), `failed`, `open` (still running) or `swept` (stalled and closed by us).
from, to	UTC days as `YYYY-MM-DD`, both included.
key_id	Only the calls made with this key.
q	Text inside the stored query.
limit	1 to 200, default 50.
cursor	The previous page's `next_cursor`.

Pages follow a cursor, so rows that arrive while you read never shift a page. When next_cursor is null there are no more rows; total counts every matching row. A malformed filter or cursor is a 400 invalid_request naming the field.

example

curl "https://metasearch.sh/api/v1/requests?status=failed&from=2026-11-01&limit=50" \
  -H "Authorization: Bearer $METASEARCH_API_KEY"

{
  "data": [
    {
      "id": "8c3d…",
      "created_at": "2026-11-03T09:14:07.512Z",
      "mode": "news",
      "status": "failed",
      …
    }
  ],
  "next_cursor": "MjAyNi0xMS0wM1Qw…",
  "total": 214
}

One request#

GET /api/v1/requests/{id} returns one call with everything in the log row, plus each attempt (engine, outcome, latency, charge) and the ledger rows the call wrote. The id is the request_id of a search response, also sent as the X-Request-Id header. An id from another organisation answers 404 not_found, the same as an id that does not exist.

Usage API errors#

A missing, unknown or revoked key gets 401 invalid_api_key, and a key past its expiry date 401 key_expired. The full list is on Errors.