Usage

Open in ChatGPT Open in Claude

Usage per product for a date range. Counts requests and credits per product from the request log. from and to accept an ISO date (UTC) or date-time. A date-only to includes that whole day. The default range is the last 30 days.

GET https://YOUR_API_HOST/v1/usage

Credits

Free. This endpoint never spends credits.

Query parameters

Field	Type	Required	Notes
`from`	string	no	Example `2026-10-01`.
`to`	string	no	Example `2026-10-31`.

Example request

Terminal

curl https://YOUR_API_HOST/v1/usage \
  -H "Authorization: Bearer $LOOKVALID_API_KEY"

1const response = await fetch("https://YOUR_API_HOST/v1/usage", {
2  headers: { Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}` },
3});
4console.log(await response.json());

1import os
2import requests
3
4response = requests.get(
5    "https://YOUR_API_HOST/v1/usage",
6    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
7    timeout=30,
8)
9print(response.json())

Response

Field	Type	Notes
`from`	string	Inclusive start. Format: date-time.
`to`	string	Exclusive end. Format: date-time.
`total`	object	-
`total.requests`	integer	-
`total.credits_charged`	integer	-
`products`	array of object	-
`products[].product`	string	-
`products[].requests`	integer	-
`products[].found`	integer	Lookups that returned data, including cache hits.
`products[].not_found`	integer	-
`products[].failed`	integer	Invalid input, rate limited, unknown product, unavailable provider, insufficient credits or internal error.
`products[].cache_hits`	integer	-
`products[].credits_charged`	integer	-

Response shape

Each value is a stand-in that shows the field type.

1{
2  "from": "string",
3  "to": "string",
4  "total": {
5    "requests": 0,
6    "credits_charged": 0
7  },
8  "products": [
9    {
10      "product": "string",
11      "requests": 0,
12      "found": 0,
13      "not_found": 0,
14      "failed": 0,
15      "cache_hits": 0,
16      "credits_charged": 0
17    }
18  ]
19}

Errors

400 invalid_input: The request input is invalid.
401 unauthorized: The API key is missing, malformed, revoked or unknown.
429 rate_limited: Too many requests for this API key.