Skip to main content

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.

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

RequestRecords ReturnedCredits Used
GET /v2/permits/search?size=100100 permits100
GET /v2/permits/search?size=10047 permits47
GET /v2/permits?id=1231 permit1
GET /v2/contractors/search?size=5050 contractors50
GET /v2/contractors?id=abc,def,ghi3 contractors3
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: 
curl -X GET "https://api.shovels.ai/v2/usage" \
  -H "X-API-Key: YOUR_API_KEY_HERE"
Response (paid plan example): 
{
  "credits_used": 1500,
  "credit_limit": 10000
}

​
Via Response Headers

Every API response includes credit tracking headers:
HeaderDescription
X-Credits-RequestCredits consumed by this request
X-Credits-LimitYour total credit limit (omitted if unlimited)
X-Credits-RemainingCredits 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.
Credits operate on a 30-day rolling window. Your usage resets based on when credits were consumed, not on a fixed calendar date.