How Many Permits Can I Retrieve Per API Call?

The number of records you can retrieve depends on the endpoint type:

Endpoint Type	Max Records	Example
Search endpoints	100 per page	`GET /v2/permits/search?size=100`
Detail endpoints	50 IDs per call	`GET /v2/permits?id=123,456,...`

Search Endpoints

Use the size parameter to control how many records are returned (default: 10, 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

Make your initial request
Check the response for next_cursor
Use that cursor value in your next request
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

​Search Endpoints

​Pagination for Larger Results

​Cursor-Based Pagination

​Detail Endpoints

​Best Practices

​Related Articles

Search Endpoints

Pagination for Larger Results

Cursor-Based Pagination

Detail Endpoints

Best Practices

Related Articles