# Exports

> Documentation index: [llms.txt](https://westkite.com/docs/llms.txt). Every page is also at its URL plus `.md`.

Exports every property that matches a filter as one CSV or NDJSON file, with an exact total and sources. $1 per 1,000 rows.

```endpoint
POST /v1/exports
GET /v1/exports/download/{file}
```

## Body

| Name | Type | Description |
|---|---|---|
| `in` | string | The market, such as `Fulton County, GA`. Send `in` or `within`. Nationwide exports aren't available. |
| `within` | object | A GeoJSON `Polygon` or `MultiPolygon` (or a `Feature` holding one) to export inside, instead of `in`: up to 8 polygons of up to 40 vertices each, longitude first. |
| `where` | array of strings | Clauses in the [find grammar](https://westkite.com/docs/api/find.md#the-where-grammar). `owner =` and `building_to_lot_ratio` are find-only; use `owner ~` here. |
| `type` | string | `properties`, the default and only type. Other types page through [find](https://westkite.com/docs/api/find.md). |
| `format` | string | `csv`, the default: a header row, then one row per property. `ndjson`: one JSON object per line, with the same columns as keys, numbers as numbers and a value the source doesn't state as `null`. |
| `max_rows` | integer | The most rows the file may hold, up to 100,000. |
| `max_cost_usd` | number | The most the file may cost. |

## Request

```curl
curl https://api.westkite.com/v1/exports \
  -H "Authorization: Bearer $WESTKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fulton-retail-2026-11" \
  -d '{
    "in": "Fulton County, GA",
    "where": ["property_type = retail", "last_sale_date >= 2021-11-01"],
    "max_cost_usd": 20
  }'
```

```typescript
const res = await fetch("https://api.westkite.com/v1/exports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WESTKITE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "fulton-retail-2026-11",
  },
  body: JSON.stringify({
    in: "Fulton County, GA",
    where: ["property_type = retail", "last_sale_date >= 2021-11-01"],
    max_cost_usd: 20,
  }),
});
const { data } = await res.json();
```

```python
import os, requests

res = requests.post(
    "https://api.westkite.com/v1/exports",
    headers={
        "Authorization": f"Bearer {os.environ['WESTKITE_API_KEY']}",
        "Idempotency-Key": "fulton-retail-2026-11",
    },
    json={
        "in": "Fulton County, GA",
        "where": ["property_type = retail", "last_sale_date >= 2021-11-01"],
        "max_cost_usd": 20,
    },
)
data = res.json()["data"]
```

## Response

```json 200
{
  "data": {
    "status": "ready",
    "scope": "Fulton County, GA",
    "total": 4182,
    "file": {
      "url": "https://api.westkite.com/v1/exports/download/west-kite-fulton-county-ga-2026-11-15.csv?token=…",
      "format": "csv",
      "rows": 4182,
      "columns": ["property_id", "address", "…"],
      "expires_at": "2026-11-16T18:00:00.000Z"
    },
    "sources": [{ "label": "Fulton County Board of Assessors" }],
    "preview": [{ "property_id": "property:3f2b9c1e-…", "address": "…" }]
  },
  "missing": [],
  "billing": { "operation_id": "op_e8f3…", "operation": "export", "charged_usd": 4.182, "balance_usd": 15.8 },
  "request_id": "req_e8f3…"
}
```

`total` is the exact number of matching properties. `preview` holds the first few rows so you can check the filter before you download. When nothing matches, `status` is `empty`, `file` is `null` and nothing is charged.

## How the charge works

The file is charged when it's prepared, for exactly the rows it holds. Your balance, `max_rows`, `max_cost_usd` and the key's [spend cap](https://westkite.com/docs/api/authentication.md#spend-caps) size the file rather than refusing it: if they cover fewer rows than match, the file holds what they cover, and `rows_left_out` and `limit_note` say how many more match. Get the exact total first, for free, with [find](https://westkite.com/docs/api/find.md) and `count=true`.

## Download

`file.url` carries its own token, so it needs no API key. Open it as often as you like for 24 hours at no further charge. It stops working when it expires or the key that made it is revoked, and then answers [`not_found`](https://westkite.com/docs/api/errors.md#not_found). The `X-West-Kite-Total-Rows` header gives the row count. A CSV file is `text/csv`; an NDJSON file is `application/x-ndjson`, and `file.columns` lists the keys every line carries.

## Errors

| Code | When |
|---|---|
| [`invalid_request`](https://westkite.com/docs/api/errors.md#invalid_request) | Neither `in` nor `within` (or both), a type other than `properties`, a format other than `csv` or `ndjson`, a find-only filter, an unknown field, or `max_rows` over 100,000. |
| [`insufficient_balance`](https://westkite.com/docs/api/errors.md#insufficient_balance) | Your balance can't cover a single row. |
| [`spend_limit_exceeded`](https://westkite.com/docs/api/errors.md#spend_limit_exceeded) | The key's monthly cap is reached. |
