Skip to main content
The number of records you can retrieve depends on the endpoint type:
Endpoint TypeMax RecordsExample
Search endpoints100 per pageGET /v2/permits/search?size=100
Detail endpoints50 IDs per callGET /v2/permits?id=123,456,...

​
Search Endpoints

Use the size parameter to control how many records are returned (default: 50, max: 100): 
curl -X GET \
  "https://api.shovels.ai/v2/permits/search?geo_id=94103&size=100" \
  -H "X-API-Key: YOUR_API_KEY_HERE"

​
Pagination for Larger Results

If you need more than 100 permits, paginate through the results using the next_cursor value provided in the response.

​
Cursor-Based Pagination

  1. Make your initial request
  2. Check the response for next_cursor
  3. Use that cursor value in your next request
  4. Repeat until no more results
# First request
GET /v2/permits/search?geo_id=CA&size=100

# Subsequent requests with cursor
GET /v2/permits/search?geo_id=CA&size=100&cursor=CURSOR_VALUE
Your API credits are based on records returned—a call returning 100 permits uses 100 credits, while a call returning 1 permit uses 1 credit.

​
Detail Endpoints

When retrieving specific records by ID, you can request up to 50 IDs per call: 
curl -X GET \
  "https://api.shovels.ai/v2/permits?id=permit_123,permit_456,permit_789" \
  -H "X-API-Key: YOUR_API_KEY_HERE"
The same limit applies to contractor lookups via GET /v2/contractors?id=....

​
Best Practices

  • Set size=100 on search endpoints to maximize records per request
  • Batch detail lookups to avoid exceeding the 50 ID limit
  • Handle pagination in your code to process complete datasets
  • Store results locally to avoid re-fetching the same data