---
title: "Usage reference"
url: "https://lookvalid.com/docs/api/usage.md"
canonical_url: "https://lookvalid.com/docs/api/usage"
last_updated: "2026-10-22"
type: "reference"
summary: "Request and response reference for Usage: parameters, response fields, credit cost and error codes."
related: ["https://lookvalid.com/docs/errors.md"]
---

# Usage reference

Request and response reference for Usage: parameters, response fields, credit cost and error codes.

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.

```http
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

**cURL**

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

**Node.js**

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

**Python**

```python
import os
import requests

response = requests.get(
    "https://YOUR_API_HOST/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
    timeout=30,
)
print(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.

```json
{
  "from": "string",
  "to": "string",
  "total": {
    "requests": 0,
    "credits_charged": 0
  },
  "products": [
    {
      "product": "string",
      "requests": 0,
      "found": 0,
      "not_found": 0,
      "failed": 0,
      "cache_hits": 0,
      "credits_charged": 0
    }
  ]
}
```

## Errors

- `400` [`invalid_input`](https://lookvalid.com/docs/errors.md#invalid_input): The request input is invalid.
- `401` [`unauthorized`](https://lookvalid.com/docs/errors.md#unauthorized): The API key is missing, malformed, revoked or unknown.
- `429` [`rate_limited`](https://lookvalid.com/docs/errors.md#rate_limited): Too many requests for this API key.

## Related

- [Errors](https://lookvalid.com/docs/errors.md)