What counts as an API request?
New accounts on Shovels receive 250 free API requests to explore our capabilities before committing to a paid plan. This article explains what constitutes an API request so you can maximize the value of those 250 pings.
Every HTTP call you make to the Shovels API—no matter which endpoint you hit—deducts 1 request from the 250-request starter quota that comes with new accounts. This applies to the search endpoints (GET /v2/permits/search, GET /v2/contractors/search) and to the detail endpoints (GET /v2/permits, GET /v2/contractors).
How many records can one request return
You can ask for up to 100 permits or contractors in a single call by setting the size (or limit) parameter to 100. Whether you retrieve 1 record or 100, it is still just one request against your quota.
Detail already included in search results
Search responses contain the full detail payload for every record returned, so you usually don’t need a separate detail call. If you do call a detail endpoint—whether for one ID or many IDs—it still counts as only one request.
Practical examples
• GET /v2/permits/search?size=100 → 1 request
• GET /v2/permits?id=123 → 1 request
• GET /v2/contractors/search?size=100 → 1 request
• GET /v2/contractors?id=abc,def,ghi → 1 request
Each of these cases consumes exactly one of your 250 free pings.
Note that the same request usage applies when you're on a paid plan!