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

# List teardowns

> Paginated list of teardowns owned by your organization.

Returns a paginated list of teardowns owned by your organization.
**Always org-scoped** unlike the UI's `GET /teardowns` (which returns
a cross-org active feed), this endpoint never returns another org's
teardowns. There is no way to opt out.

## Headers

<ParamField header="Authorization" type="string" required>
  `Bearer tdao_live_…`
</ParamField>

<ParamField header="X-Organization-Id" type="string" required>
  Your organization's UUID.
</ParamField>

## Query parameters

### Filtering

<ParamField query="asset_type" type="string">
  Filter by asset type: `aircraft` or `engine`. APU and landing-gear
  teardowns are UI-only — passing either returns `422`. Legacy rows
  with those types remain readable via the detail endpoint.
</ParamField>

<ParamField query="aircraft_type" type="string">
  Filter by aircraft-type **name** (e.g. `A320-200`). Case-insensitive.
  Unknown values return `400 unknown_vocabulary` with the allowed list.
  Same DX as the create endpoint no UUID lookup required.
</ParamField>

<ParamField query="engine_model" type="string">
  Filter by engine-model name (e.g. `CFM56-5B`). Case-insensitive.
</ParamField>

<ParamField query="status" type="string (CSV)">
  Filter by status. Comma-separated list of internal status values:
  `active_starting`, `active_in_process`, `active_completed`,
  `suspended`, `archived`.
</ParamField>

<ParamField query="country" type="string">
  Filter by country (substring match, case-insensitive). e.g. `US`.
</ParamField>

<ParamField query="search" type="string">
  Free-text search across `msn`, `registration`, and `description`.
  Substring, case-insensitive.
</ParamField>

### Sorting

<ParamField query="sort_by" type="string" default="created_at">
  One of `created_at`, `msn`, `status`, `location_country`,
  `teardown_start_date`, `asset_type`.
</ParamField>

<ParamField query="sort_dir" type="string" default="desc">
  `asc` or `desc`.
</ParamField>

### Pagination

<ParamField query="page" type="integer" default="1">
  1-indexed page number.
</ParamField>

<ParamField query="per_page" type="integer" default="20">
  Page size. Minimum 1, maximum 100.
</ParamField>

## Response

`200 OK`. Paginated envelope:

<ResponseField name="items" type="array">
  Array of teardown summary objects (similar shape to the detail
  response same field names, same partner-facing renames).
</ResponseField>

<ResponseField name="total" type="integer">
  Total count of teardowns matching the filters across all pages.
</ResponseField>

<ResponseField name="page" type="integer">
  Echo of the requested page.
</ResponseField>

<ResponseField name="per_page" type="integer">
  Echo of the requested page size.
</ResponseField>

<ResponseField name="pages" type="integer">
  Total page count for the filtered set.
</ResponseField>

<RequestExample>
  ```bash all theme={null}
  # Every teardown your org owns, most recent first
  curl "$base_url/public/v1/teardowns?page=1&per_page=20" \
    -H "Authorization: Bearer $api_key" \
    -H "X-Organization-Id: $org_id"
  ```

  ```bash aircraft theme={null}
  # Aircraft teardowns only — optionally narrowed by aircraft_type name
  curl "$base_url/public/v1/teardowns?asset_type=aircraft&aircraft_type=A320-200&per_page=20" \
    -H "Authorization: Bearer $api_key" \
    -H "X-Organization-Id: $org_id"
  ```

  ```bash engine theme={null}
  # Engine teardowns only — optionally narrowed by engine_model name
  curl "$base_url/public/v1/teardowns?asset_type=engine&engine_model=CFM56-5B&per_page=20" \
    -H "Authorization: Bearer $api_key" \
    -H "X-Organization-Id: $org_id"
  ```

  ```bash status theme={null}
  # Filter by status (CSV) and free-text search
  curl "$base_url/public/v1/teardowns?status=active_in_process,active_completed&search=12345" \
    -H "Authorization: Bearer $api_key" \
    -H "X-Organization-Id: $org_id"
  ```

  ```bash sort theme={null}
  # Sort by published-date ascending
  curl "$base_url/public/v1/teardowns?sort_by=teardown_start_date&sort_dir=asc" \
    -H "Authorization: Bearer $api_key" \
    -H "X-Organization-Id: $org_id"
  ```

  ```python python theme={null}
  import requests

  # Aircraft teardowns only
  resp = requests.get(
      f"{base_url}/public/v1/teardowns",
      headers={"Authorization": f"Bearer {api_key}", "X-Organization-Id": org_id},
      params={"asset_type": "aircraft", "aircraft_type": "A320-200", "per_page": 50},
  )

  # Engine teardowns only
  resp = requests.get(
      f"{base_url}/public/v1/teardowns",
      headers={"Authorization": f"Bearer {api_key}", "X-Organization-Id": org_id},
      params={"asset_type": "engine", "engine_model": "CFM56-5B", "per_page": 50},
  )
  resp.raise_for_status()
  page = resp.json()
  print(f"Got {len(page['items'])} of {page['total']} teardowns")
  ```
</RequestExample>

<ResponseExample>
  ```jsonc 200 OK theme={null}
  {
    "items": [
      {
        "id": "3c707051-021d-4d04-a8e7-4eb254e80858",
        "org_id": "72f95f4e-65bb-41b3-8ef4-226c5a59cbc1",
        "asset_type": "aircraft",
        "aircraft_type": { "name": "A320-200", "manufacturer": "Airbus", ... },
        "msn": "12345",
        "registration": "VT-ABC",
        "status": "active_starting",
        "teardown_status_label": "Starting",
        "location": "Tucson, AZ",
        "location_country": "US",
        "description": "Posted from ERP",
        "published_at": "2026-05-26T20:06:50.677262Z",
        "created_at": "2026-05-26T20:06:48.825931Z"
      }
      // ... up to per_page items
    ],
    "total": 7,
    "page": 1,
    "per_page": 20,
    "pages": 1
  }
  ```
</ResponseExample>

<Note>
  The list endpoint currently returns the legacy field names
  (`id` / `registration` / `location_country`) rather than the
  partner-facing aliases (`teardown_id` / `tail_number` / `country`) the
  detail endpoint uses. We're aligning the shapes in a future release;
  for now, branch on `id` in list responses and `teardown_id` in detail
  responses. Both refer to the same UUID.
</Note>

## Pagination patterns

For partners syncing all teardowns into an ERP, the typical loop:

```python theme={null}
page = 1
while True:
    resp = requests.get(
        f"{base_url}/public/v1/teardowns",
        headers=headers,
        params={"page": page, "per_page": 100},
    )
    data = resp.json()
    for td in data["items"]:
        upsert_into_erp(td)
    if page >= data["pages"]:
        break
    page += 1
```

For incremental sync (catching new teardowns since last run), filter
by `sort_by=created_at&sort_dir=desc` and stop when you see a
teardown you've already imported. We don't currently expose a
"created\_after" filter request via support if you need one.

## See also

* [Get one teardown](/api-reference/teardowns/get) for full detail.
* [Vocabularies](/concepts/vocabularies) for the accepted names the
  `aircraft_type` / `engine_model` filters expect.
* [Rate limiting](/concepts/rate-limiting) for the pagination cadence
  your loop should use.