> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Do API Credits Work?

> The Shovels API uses a record-based credit system. Each record returned counts against your credits—a search returning 100 permits uses 100 credits, while a single permit lookup uses 1.

**The Shovels API uses a record-based credit system.** Each record returned by an API call counts against your credits. A permit search that returns 100 results uses 100 credits, while a detail lookup for a single permit uses 1 credit.

## How Credits Are Counted

Your credits are based on **records returned**, not the number of API calls you make:

* A search returning **100 permits** = **100 credits used**
* A search returning **50 contractors** = **50 credits used**
* A detail lookup for **1 permit** = **1 credit used**
* A detail lookup for **3 contractors** = **3 credits used**

This applies to all endpoints:

* Search endpoints (`GET /v2/permits/search`, `GET /v2/contractors/search`)
* Detail endpoints (`GET /v2/permits`, `GET /v2/contractors`)

## Practical Examples

| Request                              | Records Returned | Credits Used |
| ------------------------------------ | ---------------- | ------------ |
| `GET /v2/permits/search?size=100`    | 100 permits      | 100          |
| `GET /v2/permits/search?size=100`    | 47 permits       | 47           |
| `GET /v2/permits?id=123`             | 1 permit         | 1            |
| `GET /v2/contractors/search?size=50` | 50 contractors   | 50           |
| `GET /v2/contractors?id=abc,def,ghi` | 3 contractors    | 3            |

<Info>
  The credit system described above applies to **paid plans**. The free trial uses a simpler request-based system where each API call counts as 1 request, regardless of records returned.
</Info>

## Managing Your Credits

1. **Use filters effectively** - Narrow your searches to return only the records you need
2. **Use search endpoints** - They include full details in the response, avoiding extra lookups
3. **Cache results locally** - Store fetched data to avoid re-fetching the same records

## Tracking Your Usage

### Via API

Use the `GET /v2/usage` endpoint to check your credit consumption:

```bash theme={null}
curl -X GET "https://api.shovels.ai/v2/usage" \
  -H "X-API-Key: YOUR_API_KEY_HERE"
```

Response (paid plan example):

```json theme={null}
{
  "credits_used": 1500,
  "credit_limit": 10000
}
```

### Via Response Headers

Every API response includes credit tracking headers:

| Header                | Description                                    |
| --------------------- | ---------------------------------------------- |
| `X-Credits-Request`   | Credits consumed by this request               |
| `X-Credits-Limit`     | Your total credit limit (omitted if unlimited) |
| `X-Credits-Remaining` | Credits remaining (omitted if unlimited)       |

### Via Profile Settings

You can also view credit usage in the **Profile Settings** section of your account at [app.shovels.ai](https://app.shovels.ai/profile-settings/).

<Info>
  Credits operate on a **30-day rolling window**. Your usage resets based on when credits were consumed, not on a fixed calendar date.
</Info>

## Related Articles

* [API credit limits](/docs/knowledge-base/api/basics/credit-limits)
* [Permits per API call](/docs/knowledge-base/api/basics/permits-per-call)