> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shovels.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Does CLI Output and Pagination Work?

> The Shovels CLI outputs JSON to stdout with automatic pagination. Learn about response formats, the --limit flag, and credit tracking.

**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)

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

### Batch Responses (get commands)

```json theme={null}
{
  "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.

<Info>
  `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.
</Info>

### 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:

```bash theme={null}
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`) |

```bash theme={null}
# 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):

```bash theme={null}
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:

```bash theme={null}
shovels permits search --geo-id 92024 \
  --permit-from 2024-01-01 --permit-to 2024-12-31 \
  --tags solar --include-count --limit 1
```

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

<Info>
  Total counts are exact up to 10,000 (`"relation": "eq"`). Above 10,000, the count is approximate (`"relation": "gte"` means "at least this many").
</Info>

## 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:

```json theme={null}
{
  "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](/docs/knowledge-base/cli/absence-and-trust).

## 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:

```bash theme={null}
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%           |

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

## Related Articles

* [CLI commands overview](/docs/knowledge-base/cli/commands-overview) — Full list of commands and flags
* [CLI absence searches and trust fields](/docs/knowledge-base/cli/absence-and-trust) — Reading `meta.trust_summaries`
* [CLI error codes](/docs/knowledge-base/cli/error-codes) — Understanding error responses
* [Scripting and AI agents](/docs/knowledge-base/cli/scripting-and-agents) — Piping CLI output into workflows