Skip to main content
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

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.

​
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:
Response (paid plan example):

​
Via Response Headers

Every API response includes credit tracking headers:

​
Via Profile Settings

You can also view credit usage in the Profile Settings section of your account at app.shovels.ai.
Credits operate on a 30-day rolling window. Your usage resets based on when credits were consumed, not on a fixed calendar date.