---
title: "One carrier's cross-state footprint for a line and year"
method: GET
path: "/v1/carriers/footprint"
---

# One carrier's cross-state footprint for a line and year

`GET /v1/carriers/footprint`

## Request

- Base URL: `https://api.querylines.com`
- URL: `https://api.querylines.com/v1/carriers/footprint`
- Auth: none declared

$0.50 per query -- the cross-state differentiator (CLAUDE.md), same pricing tier as GET /v1/compare. Default `states`: every jurisdiction where the code appears in that year's tables (top-10 truncation applies -- a state's absence means the code fell outside that state's top 10, not zero business there). `us` is the countrywide reference row.

## Query parameters

- `code` string, required
- `line` string
- `year` integer
- `states` string

## Response `200`

Per-state rows plus the countrywide reference row.

- object
  - `code` string, required
  - `name` string, nullable, required
  - `entity_kind` 'group' | 'company' | 'null', nullable, required
  - `line` string, required
  - `line_name` string, required
  - `year` number, required
  - `states` object[], required
    - `state` string, required
    - `rank` number, nullable, required
    - `dpw` number, nullable, required
    - `market_share` number, nullable, required
    - `yoy_dpw_pct` number, nullable, required
  - `us` object, nullable, required
    - `rank` number, nullable, required
    - `dpw` number, nullable, required
    - `market_share` number, nullable, required
    - `yoy_dpw_pct` number, nullable, required
  - `report_date` string, nullable, required
  - `data_as_of` string, nullable, required
  - `source` string, nullable, required
  - `coverage_note` string, required: Top-125 countrywide / top-10 per jurisdiction ONLY -- absence from these results does NOT mean a carrier writes no business there. Repeated verbatim on every response (see GET /v1/carriers/lines).

## Other responses

- `400`: Invalid query parameters.
- `402`: Payment required (x402). Returned when the x402 payment gate is enabled (PAY_TO_ADDRESS configured) and the request carries no valid payment. The full payment challenge (price/network/payTo/asset) is carried in the base64-encoded PAYMENT-REQUIRED response header (see the x402 spec), not the JSON body -- the body is `{}` for API clients. Price for this route: $0.50. Retry with a signed payment per x402 (USDC on Base mainnet); on success the response carries a PAYMENT-RESPONSE header with settlement info. When PAY_TO_ADDRESS is unset (kill switch off), this route is free and never returns 402.
- `404`: Unknown state or coverage line.
- `500`: Internal error.

---

[API](https://skmtc.dev/querylines/apis/querylines-api.md) · [All operations](https://skmtc.dev/querylines/apis/querylines-api/llms.txt) · [OpenAPI document](https://skmtc.dev/querylines/apis/querylines-api/revisions/4afb6c3e2b1f?raw)