How Does CLI Output and Pagination Work?

All CLI output is valid JSON written to stdout. Errors go to stderr. This makes the CLI safe to pipe into jq, scripts, or other tools without worrying about mixed output.

Response Format

Paginated Responses (search commands)

{
  "data": [
    { "id": "...", "description": "...", "status": "final" }
  ],
  "meta": {
    "count": 50,
    "has_more": true,
    "credits_used": 1,
    "credits_remaining": 9999
  }
}

Batch Responses (get commands)

{
  "data": [
    { "id": "ABC", "name": "..." },
    { "id": "DEF", "name": "..." }
  ],
  "meta": {
    "count": 2,
    "missing": ["UNKNOWN_ID"],
    "credits_used": 1,
    "credits_remaining": 9999
  }
}

The missing array lists any IDs that weren’t found, and is omitted entirely when every requested ID resolved.

data is always an array on get commands, including when you request a single ID. Write jq '.data[0]' rather than jq '.data' so a one-ID lookup and a fifty-ID batch parse the same way.

Credit Fields

credits_remaining appears only when your account has a credit limit. On uncapped plans the key is absent while credits_used is still reported, so test for it before reading it:

jq '.meta.credits_remaining // "uncapped"'

Pagination with —limit

The --limit flag controls how many records to return. The CLI handles cursor-based pagination internally — you never need to manage cursors yourself.

Value	Behavior
`--limit 50` (default)	Return up to 50 records
`--limit 500`	Return up to 500 records
`--limit all`	Fetch all records (capped by `--max-records`)

# Get first 10 results
shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --limit 10

# Get all results (up to 10,000 by default)
shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --limit all

—max-records

When using --limit all, the --max-records flag sets the upper bound (default: 10,000, maximum: 100,000):

shovels permits search --geo-id CA \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --tags solar --limit all --max-records 50000

—include-count

Add --include-count to include the total number of matching records in the response:

shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --tags solar --include-count --limit 1

{
  "data": ["..."],
  "meta": {
    "count": 1,
    "has_more": true,
    "total_count": {
      "value": 581,
      "relation": "eq"
    },
    "credits_used": 1,
    "credits_remaining": 9999
  }
}

Total counts are exact up to 10,000 ("relation": "eq"). Above 10,000, the count is approximate ("relation": "gte" means “at least this many”).

Per-Page Metadata: meta.trust_summaries

Most meta fields are aggregated across the pages --limit fetched. One is not. Absence searches on properties search return a trust summary per API page, scoped to that page’s rows. Since no single summary is correct for a merged result, the CLI collects them into a meta.trust_summaries array instead of combining them:

{
  "meta": {
    "count": 205,
    "has_more": true,
    "credits_used": 205,
    "trust_summaries": [
      { "rows_flagged": 95,  "expected_miss_rate": 0.0416, "suppressed_scopes": 0 },
      { "rows_flagged": 100, "expected_miss_rate": 0.0320, "suppressed_scopes": 0 },
      { "rows_flagged": 5,   "expected_miss_rate": 0.0320, "suppressed_scopes": 0 }
    ]
  }
}

Three entries because 205 records arrived as three pages (100 + 100 + 5). The key is omitted entirely when a query has no absence filter. See CLI absence searches and trust fields.

Credit Tracking

Every response includes credits_used in the meta object, plus credits_remaining on plans with a credit limit. This lets you monitor usage without making a separate API call. To check your overall credit status:

shovels usage

Data Types in Responses

Field Type	Format	Example
Dates	ISO 8601 (`YYYY-MM-DD`)	`"2024-06-15"`
Money amounts	Integer cents	`150000` = $1,500.00
Ratings	Float 0-5	`4.2`
Pass rates	Integer 0-100	`85` (percentage)
Coordinates (permits, addresses)	`address.latlng` as `[lat, lng]` float array	`[33.071202, -117.300993]`
Coordinates (properties)	Separate `lat` and `long` floats	`33.066977`, `-117.247426`
geo_ids	Base64-encoded string	`"Q2l0eXxGTHxNaWFtaQ"`
Rate fields (trust)	Float 0-1	`0.0769` = 7.69%

Run shovels schema <command> to get every field’s type and unit for a specific command, offline and without spending credits.

CLI commands overview — Full list of commands and flags
CLI absence searches and trust fields — Reading meta.trust_summaries
CLI error codes — Understanding error responses
Scripting and AI agents — Piping CLI output into workflows

​Response Format

​Paginated Responses (search commands)

​Batch Responses (get commands)

​Credit Fields

​Pagination with —limit

​—max-records

​—include-count

​Per-Page Metadata: meta.trust_summaries

​Credit Tracking

​Data Types in Responses

​Related Articles

Response Format

Paginated Responses (search commands)

Batch Responses (get commands)

Credit Fields

Pagination with —limit

—max-records

—include-count

Per-Page Metadata: meta.trust_summaries

Credit Tracking

Data Types in Responses

Related Articles