Spend

What searches cost, by service and by day.

Read what searches used and what is left

GET/api/v1/search/usage

What the caller's searches used over the last days UTC days, today included: calls and failures per outside service, then per day. Deleted searches still count. Tokens and dollars are Livia staff's: they are in the answer only when the key's maker is Livia staff, with live dollars kept apart from the projected dollars of stand-ins, which are never a charge.

allowance says what the key may still start this month: the org's pool, the person's own matches and limit, and left, the matches before one is refused (out-of-credits or person-limit-reached, both 402). A match counts when its run lands, so one still running is not in used yet. Read it before you start paid work.

An API key carrying the scope named here, or a signed-in session.

Scope: search:read
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`days`	Query	`integer`	Optional	How many UTC days back, today included. 30 when absent; clamped to the range.

Examples

curl "https://liviamatch.com/api/v1/search/usage" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The spend report.

A month

{
  "data": {
    "since": "2026-09-03",
    "days": 30,
    "usage": {
      "calls": 188,
      "failedCalls": 1,
      "byService": [
        {
          "service": "openrouter",
          "mode": "live",
          "calls": 52,
          "failed": 0,
          "units": null,
          "latencyMs": 61300
        }
      ]
    },
    "byDay": [
      {
        "day": "2026-09-30",
        "service": "openrouter",
        "mode": "live",
        "calls": 52,
        "failed": 0,
        "units": null,
        "latencyMs": 61300
      },
      {
        "day": "2026-10-02",
        "service": "openrouter",
        "mode": "live",
        "calls": 52,
        "failed": 0,
        "units": null,
        "latencyMs": 61300
      }
    ],
    "allowance": {
      "period": "2026-10",
      "org": {
        "used": 38,
        "allowance": 200
      },
      "person": {
        "used": 31,
        "limit": 60,
        "limitFrom": "default"
      },
      "left": 29
    }
  }
}

Fields (42)

Field	Type	Description
`data`	`object`
`data.since`	`string (date)`	The first UTC day counted.
`data.days`	`integer`
`data.usage`	`object`
`data.usage.calls`	`integer`
`data.usage.failedCalls`	`integer`
`data.usage.inputTokens`	`integer, optional`	Livia staff only. Tokens sent, across every service. Omitted unless the caller, or the key's maker, is Livia staff.
`data.usage.outputTokens`	`integer, optional`	Livia staff only. Tokens received, across every service. Omitted unless the caller, or the key's maker, is Livia staff.
`data.usage.costUsd`	`object, optional`	Livia staff only. Live dollars, apart from the projected dollars of stand-ins, which are never a charge. Omitted unless the caller, or the key's maker, is Livia staff.
`data.usage.costUsd.live`	`number`
`data.usage.costUsd.mockProjected`	`number`
`data.usage.byService`	`object[]`
`data.usage.byService[].service`	`"openrouter" \| "tavily" \| "mls" \| "travel" \| "places" \| "fair-housing" \| "compute" \| "webhooks"`
`data.usage.byService[].mode`	`"live" \| "mock"`	`live` is a real provider; `mock` is a deterministic stand-in.
`data.usage.byService[].calls`	`integer`
`data.usage.byService[].failed`	`integer`
`data.usage.byService[].inputTokens`	`integer \| null, optional`	Livia staff only. Tokens sent; null when the provider reported none. Omitted unless the caller, or the key's maker, is Livia staff.
`data.usage.byService[].outputTokens`	`integer \| null, optional`	Livia staff only. Tokens received; null when the provider reported none. Omitted unless the caller, or the key's maker, is Livia staff.
`data.usage.byService[].units`	`number \| null`
`data.usage.byService[].costUsd`	`number \| null, optional`	Livia staff only. Dollars, a projection for a stand-in; null when nobody priced the calls. Omitted unless the caller, or the key's maker, is Livia staff.
`data.usage.byService[].latencyMs`	`number`
`data.byDay`	`object[]`
`data.byDay[].service`	`"openrouter" \| "tavily" \| "mls" \| "travel" \| "places" \| "fair-housing" \| "compute" \| "webhooks"`
`data.byDay[].mode`	`"live" \| "mock"`	`live` is a real provider; `mock` is a deterministic stand-in.
`data.byDay[].calls`	`integer`
`data.byDay[].failed`	`integer`
`data.byDay[].inputTokens`	`integer \| null, optional`	Livia staff only. Tokens sent; null when the provider reported none. Omitted unless the caller, or the key's maker, is Livia staff.
`data.byDay[].outputTokens`	`integer \| null, optional`	Livia staff only. Tokens received; null when the provider reported none. Omitted unless the caller, or the key's maker, is Livia staff.
`data.byDay[].units`	`number \| null`
`data.byDay[].costUsd`	`number \| null, optional`	Livia staff only. Dollars, a projection for a stand-in; null when nobody priced the calls. Omitted unless the caller, or the key's maker, is Livia staff.
`data.byDay[].latencyMs`	`number`
`data.byDay[].day`	`string (date)`
`data.allowance`	`object`
`data.allowance.period`	`string`	The UTC month the numbers are for, `2026-10`.
`data.allowance.org`	`object`	The org's pool, shared by everyone in it.
`data.allowance.org.used`	`integer`	Matches the whole org has started this month.
`data.allowance.org.allowance`	`integer`	Matches the org may start this month.
`data.allowance.person`	`object`	The person the key acts as.
`data.allowance.person.used`	`integer`	Matches the person the key acts as has started this month.
`data.allowance.person.limit`	`integer \| null`	Their own monthly limit, a cap inside the pool; null when they have none and share the pool.
`data.allowance.person.limitFrom`	`"person" \| "default" \| "none"`	Where the limit comes from: `person` (set for them), `default` (the org's default) or `none`.
`data.allowance.left`	`integer`	Matches the key may still start before one is refused: the pool's room, or the person's own if that is smaller. Never below 0.at least 0

Errors

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal