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

# Permits parcels

> One row per parcel with building permits in one county, or for a list of parcel ids, with permit counts, the latest date, open permits and work tags.

`POST /v1/permits/parcels` returns one row per parcel that has permits tied to it.
Use it to:

* find the parcels in a county with recent work of one kind;
* read the permit summary of up to 100 parcels you already know.

> [!NOTE]
>
> * Each row returned costs one permit row: **\$0.012** on Free, **\$0.0086** on
>   Build and **\$0.0072** on Growth. See [Pricing](https://docs.mireye.ai/pricing.md).
> * A call that returns no row is free, including a count (`limit: 0`).
> * It needs accepted terms and licensed access with the `earth.search` scope, the same
>   as a permits search. See [Authentication](https://docs.mireye.ai/authentication.md).

## Example: parcels with a solar permit since 2025

```bash theme={null}
curl -sS --max-time 60 https://api.mireye.com/v1/permits/parcels \
  -H "X-API-Key: $MIREYE_API_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'content-type: application/json' \
  -d '{
    "where": {"state": "TX", "county_fips": "48157"},
    "with": {"work_tags": ["solar"], "since": "2025-01-01"},
    "sort": "latest_date_desc",
    "limit": 1,
    "max_cost_usd": "0.20"
  }' | jq
```

```json theme={null}
{
  "rows": [
    {
      "parcel_id": "11111111-2222-3333-4444-555555555555",
      "permit_address": "1234 EXAMPLE DR, EXAMPLE, TX 77479",
      "permit_count": 4,
      "latest_date": "2025-03-04",
      "open_permits": 1,
      "tags": {
        "electrical": {"count": 2, "latest_date": "2025-03-04"},
        "solar": {"count": 1, "latest_date": "2025-03-04"}
      },
      "coverage": "complete"
    }
  ],
  "total_parcels": 1873,
  "next_cursor": "q9cS0k1u…",
  "coverage": "partial",
  "note": "Not every permit office here is collected in full with most of its permits tied to parcels, so counts are a lower bound and a parcel missing from the rows may still have permits. Counts include permits tied to a parcel with a usable date from 2024-07-01 on; older permits are history records and are not counted.",
  "billing": {
    "operation_id": "op_4b1d…",
    "currency": "USD",
    "charged_usd": "0.012000",
    "pricing_version": "earth-usd-v1",
    "replayed": false
  }
}
```

Values are illustrative.

Over hosted MCP, the tool is `mireye_permits_parcels`. Send the same body inside `req`:

```json theme={null}
{
  "req": {
    "where": {"parcels": ["11111111-2222-3333-4444-555555555555"]},
    "limit": 100
  },
  "idempotency_key": "parcel-permits-rollup-0001"
}
```

## Request

| Field | Type | Required | Default | Notes |
| - | - | - | - | - |
| `where` | object | yes | | One county, or a list of parcels. See [where](#where). |
| `with` | object | no | | Keep only parcels that have a matching permit. See [with](#with). |
| `filters` | object | no | `{}` | Narrow the permits that are counted. See [filters](#filters). |
| `sort` | string | no | `permit_count_desc` | `permit_count_desc` (most permits first) or `latest_date_desc` (most recent first). |
| `limit` | integer | no | `100` | Rows per page, 0 to 500. `0` is a free count: `total_parcels` only. It holds one row while it runs. |
| `cursor` | string | no | | The previous page's `next_cursor`. Not with `limit: 0`. |
| `max_cost_usd` | decimal string | no | | Spending ceiling for this page, such as `"0.20"`. |

* Any other key is rejected with `422`.
* `without` is not supported yet: it is rejected with `422 not_yet_supported`.

### where

Send one of:

* `{"state": "TX", "county_fips": "48157"}`: the parcels in one county. `county_fips`
  is five digits and must be in `state`.

* `{"parcels": ["…", "…"]}`: 1 to 100 parcel ids, each a lowercase UUID such as
  `"11111111-2222-3333-4444-555555555555"`. Get them from `parcel.parcel_id` of a
  permit record, or from Enrich or Search.

* A parcel with no counted permit has no row.

* With a list of parcels, a parcel may be missing from the rows. Then it has no
  counted permit, or its office is not fully collected.

* Read `coverage` before you treat it as "no permits".

### with

A parcel is kept when at least one of its counted permits matches every part you
send:

| Key | Type | Meaning |
| - | - | - |
| `work_tags` | list | Any of these work tags. A parent tag also matches its child tags: `electrical` matches `solar`. |
| `category` | list | Any of these permit categories. |
| `since` | date | The permit's first recorded date is on or after this date. `YYYY-MM-DD`. |

Values are the [Permits API vocabulary](https://docs.mireye.ai/api-reference/permits.md#vocabulary). An unknown
value is rejected with the nearest valid values.

### filters

`filters` narrows which permits are counted in each row. The row's counts, dates and
tags then cover only those permits. These keys work, with the same meaning as in a
[permits search](https://docs.mireye.ai/api-reference/permits.md#filters):

`date_field`, `date_from`, `date_to`, `status`, `category`, `work_tags`, `tags_match`,
`min_date_precision` and `include_reissued`.

Any other filter is rejected with `422 permits_filter_unsupported`. Its `filters` key
lists the filters that cannot be used.

## Which permits count

A permit counts for a parcel by the same rule as the
[Enrich permit fields](https://docs.mireye.ai/api-reference/enrich-permit-fields.md#which-permits-count):

* It is tied to the parcel with `high` or `medium` link confidence.
* It has a day, month or year date.
* It is not undated and not an older history record.

One job filed as several linked records counts once. With no `filters`, a row's
`permit_count`, `latest_date` and `tags` equal the Enrich permit fields for that
parcel.

## Response

| Key | Type | Meaning |
| - | - | - |
| `rows` | array | One row per parcel. See [Row](#row). |
| `total_parcels` | integer | How many parcels match, on all pages. |
| `next_cursor` | string or `null` | Send it as `cursor` for the next page. `null` on the last page. |
| `coverage` | string or `null` | `complete` when every county read is complete, `not_collected` when none is collected, else `partial`. |
| `note` | string or `null` | What the counts may miss, and the date the counts start. |
| `billing` | object | The receipt. |

### Row

| Key | Meaning |
| - | - |
| `parcel_id` | The parcel's id. |
| `permit_address` | The address of the parcel's latest counted permit, as the permit gives it. `null` when it has none. |
| `permit_count` | Counted permits tied to the parcel. |
| `latest_date` | The latest first recorded date among those permits. |
| `open_permits` | Of those permits, the ones with status `in_review` or `active`. A permit with status `unknown` is not counted as open. |
| `tags` | Per work tag: `count` and `latest_date`. Only tags with at least one permit appear. |
| `coverage` | The coverage word for this parcel, as in the [Enrich permit fields](https://docs.mireye.ai/api-reference/enrich-permit-fields.md#coverage). |

## Paging

* Send `next_cursor` as `cursor` with the same body. `limit` and `max_cost_usd` may
  change.
* A cursor expires after one hour, or when the permit data is refreshed. Then the
  answer is `422 permits_cursor_expired`: start again without a cursor.
* Each page is a new paid call with its own `Idempotency-Key`.

## Price

* One permit row for each row returned.
* The most it can cost, `limit` rows, is reserved first. Set `max_cost_usd` at or
  above it.
* A call with no row is free:
  * a count (`limit: 0`);
  * no matching parcel;
  * a call that fails.
* Send a stable `Idempotency-Key` to retry without a second charge. See
  [Retries](https://docs.mireye.ai/api-reference/permits.md#retries).

## Errors

| HTTP | Code | Meaning |
| - | - | - |
| 422 | `permits_invalid_request` | The request is not valid. `problems` lists the bad inputs. |
| 422 | `permits_filter_unsupported` | A filter cannot be applied to parcel rows: `filters` names it. Or a `date_field` other than `earliest` needs milestone dates the data does not have yet. |
| 422 | `not_yet_supported` | `without` is not supported yet. Use `with`. |
| 422 | `permits_cursor_invalid` | The cursor is not valid for this request. |
| 422 | `permits_cursor_expired` | The cursor expired, or the permit data was refreshed. |

The other errors are the same as a permits search. See
[Errors](https://docs.mireye.ai/api-reference/permits.md#errors).

## Related pages

* [Permits API](https://docs.mireye.ai/api-reference/permits.md): the permit records themselves.
* [Permits stats](https://docs.mireye.ai/api-reference/permits-stats.md): counts grouped by month, tag,
  category or office.
* [Enrich permit fields](https://docs.mireye.ai/api-reference/enrich-permit-fields.md): the same counts for one
  parcel.
* [Permits known issues](https://docs.mireye.ai/api-reference/permits-known-issues.md).
