Skip to main content
One credit is one record. You pay for the records you take, not for the requests you make. Credits are spent two ways:
  • Records returned by the API. A permit search that returns 100 results uses 100 credits; a detail lookup for a single permit uses 1.
  • Records exported from Shovels Online. A CSV export of 5,000 contractors uses 5,000 credits.
Everything else is free. Searching, filtering, paging through results, opening a record, using the map, and asking Charlie cost nothing — browse as much as you like.

​
How Credits Are Counted

Credits are based on records, not on the number of requests 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

This applies to every plan, including Free. There is no separate request-based metering.

​
Exports From Shovels Online

Exporting search results to CSV spends one credit per record exported, the same rate as the API. The export covers the full set of matching records, so check your remaining balance before exporting a large result set. Export requires a paid plan. Browsing those same results costs nothing — you only spend credits at the point you take the records out.

​
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 your account page

You can also view credit usage on the Manage subscription tab at app.shovels.ai/account.
Credits reset monthly on your subscription or upgrade date.