---
title: "Tracked military aircraft"
description: "Lists military aircraft positions from the adsb.lol community ADS-B network (aircraft the ADS-B database flags as military), classified by type such as tanker, AWACS, or fighter and assigned to the smallest configured theater. Positions refresh every 15 minutes, expire 30 minutes after `lastSeenAt`, and carry a `source` linking to the aircraft on adsb.lol. Data: adsb.lol, ODbL 1.0. Accepts a bearer API key or [x402 payment](https://y2.dev/docs/api/x402). Without a key, read the `402` challenge in `PAYMENT-REQUIRED`. Retry with `PAYMENT-SIGNATURE`."
canonical: https://y2.dev/docs/api/reference/osint/listAircraft/
---

Endpoint Reference[OSINT](https://y2.dev/docs/api/reference/osint)

# Tracked military aircraft

Lists military aircraft positions from the adsb.lol community ADS-B network (aircraft the ADS-B database flags as military), classified by type such as tanker, AWACS, or fighter and assigned to the smallest configured theater. Positions refresh every 15 minutes, expire 30 minutes after \`lastSeenAt\`, and carry a \`source\` linking to the aircraft on adsb.lol. Data: adsb.lol, ODbL 1.0. Accepts a bearer API key or \[x402 payment]\(https\://y2.dev/docs/api/x402). Without a key, read the \`402\` challenge in \`PAYMENT-REQUIRED\`. Retry with \`PAYMENT-SIGNATURE\`.

`GET https://api.y2.dev/api/v1/osint/aircraft`

- Operation ID: `listAircraft`
- Required scopes: `osint:read`
- Accepts x402 pay-per-request payment
- Contract: https://y2.dev/openapi.json

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `theater` | query | string | No | Filter by theater ID (e.g. "iran", "taiwan", "blacksea", "scs") |
| `limit` | query | integer | No | Maximum number of aircraft to return |
| `cursor` | query | string | No | Opaque continuation token from the previous response. Bound to the original filters and ordering. |
| `format` | query | `json`, `ndjson`, `geojson` | No | Select the JSON resource envelope, row-oriented NDJSON, or an RFC 7946 FeatureCollection. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | List of tracked military aircraft | `AircraftListResponse` |
| 400 | Invalid request parameters |  |
| 401 | Missing or invalid API key |  |
| 402 | x402 payment required | `X402PaymentRequiredResponse` |
| 403 | Insufficient permissions or access denied |  |
| 429 | Rate limit exceeded (per-key or per-account aggregate) |  |
| 500 | Internal server error |  |

### 200 response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[]` | array of `AircraftTrack` |  |
| `data[].id` | string | Public observation identifier for this position. |
| `data[].type` | string |  |
| `data[].icao24` | string | ICAO 24-bit transponder address, lowercase hex. |
| `data[].callsign` | string | Aircraft callsign, or `UNKNOWN`. |
| `data[].registration` | string or null | Registration as reported by ADS-B, when known. |
| `data[].typeCode` | string or null | ICAO type designator such as `KC135`, when known. |
| `data[].squawk` | string or null | Transponder squawk, when known. |
| `data[].aircraftType` | `fighter`, `tanker`, `awacs`, `recon`, `transport`, `bomber`, `drone`, `military_generic`, `unknown` | Y2's type classification. `military_generic` means only the ADS-B database military flag is known. |
| `data[].operator` | string | Operating entity, or `unknown`. |
| `data[].confidence` | `high`, `medium`, `low` | Classification confidence. |
| `data[].coordinates` | object |  |
| `data[].geometry` | `GeoJSONPoint` | WGS 84 point with longitude first, then latitude. |
| `data[].altitude` | number | Barometric altitude in meters; 0 on the ground. |
| `data[].heading` | number | Track over ground in degrees true. |
| `data[].speed` | number | Ground speed in meters per second. |
| `data[].position` | object |  |
| `data[].motion` | object |  |
| `data[].theater` | string | Smallest configured theater containing the position. |
| `data[].isInteresting` | boolean | Bomber, AWACS, reconnaissance aircraft, or an emergency squawk. |
| `data[].lastSeenAt` | integer (int64) | Last seen time as Unix timestamp (milliseconds) |
| `data[].lastSeenAtISO` | string (date-time) | Last seen time as ISO 8601 string |
| `data[].observedAt` | string (date-time) | The `lastSeenAt` value as ISO 8601. |
| `data[].source` | `RecordSource` | Where a record came from, how Y2 obtained it, and when. |
| `meta` | object |  |
| `meta.emptyReason` | `no_matching_activity`, `source_degraded`, `source_stale`, `source_unavailable`, `source_unknown`, `null` |  |
| `meta.sourceStatus` | `healthy`, `degraded`, `stale`, `unavailable`, `unknown` |  |
| `meta.lastSuccessfulIngestAt` | string or null (date-time) |  |
| `meta.count` | integer |  |
| `meta.limit` | integer |  |
| `meta.hasMore` | boolean | Whether more results are available beyond the current limit |
| `meta.filters` | object |  |
