---
title: "Query the OSINT API"
description: "Read normalized events, country intelligence, geospatial feeds, source health, and FININT"
canonical: https://y2.dev/docs/api/osint/
---

# Query the OSINT API

Read normalized events, country intelligence, geospatial feeds, source health, and FININT

The OSINT API exposes source-oriented Situation Room data as canonical public resources. Use it for normalized event feeds, geospatial observations, country surfaces, provider health, prediction markets, transport and security feeds, or financial indicators.

The base URL is:

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

## Choose an endpoint

### Events and geography

| Goal                                 | Endpoint         | Useful filters                                                   |
| ------------------------------------ | ---------------- | ---------------------------------------------------------------- |
| List normalized threat events        | `GET /events`    | `category`, `severity`                                           |
| Load only geolocated map events      | `GET /map`       | `region`                                                         |
| Compose regional and spatial filters | `GET /regional`  | `q`, `region`, `countryCode`, `sourceType`, `bbox`, radius, time |
| Read report-extracted events         | `GET /y2-events` | `category`, `severity`, `countryCode`                            |

### Country intelligence

| Goal                                                        | Endpoint                                   |
| ----------------------------------------------------------- | ------------------------------------------ |
| Periodically generated intelligence brief                   | `GET /countries/{countryCode}/brief`       |
| Primary stock index and weekly change                       | `GET /countries/{countryCode}/markets`     |
| Country-linked prediction markets                           | `GET /countries/{countryCode}/predictions` |
| Recent news and report observations attributed to a country | `GET /countries/{countryCode}/news`        |
| Country Conflict Indicators Index                           | `GET /countries/{countryCode}/cii`         |

Country codes are ISO 3166-1 alpha-2 values such as `US` or `UA`.

### Specialized feeds

| Family                | Endpoints                                                     |
| --------------------- | ------------------------------------------------------------- |
| Conflict and security | `/cii`, `/cyber-threats`, `/military-posture`, `/gps-jamming` |
| Transport             | `/aircraft`, `/vessels`                                       |
| Markets               | `/prediction-markets`, `/finint`                              |
| Operations            | `/sources/status`                                             |

Aircraft feeds run on adsb.lol; GPS interference is paused

`/aircraft` and `/military-posture` refresh every 15 minutes from the adsb.lol community ADS-B network (ODbL 1.0). Rows carry a `source` object, and posture covers the nine conflict theaters with calibrated thresholds. `/gps-jamming` lost its Wingbits source on October 26, 2026, and returns an empty collection with `sourceStatus: unavailable` until it is re-sourced.

## Authenticate or use x402

Every published OSINT operation accepts a bearer key with `osint:read` or its documented [x402 pay-per-request flow](https://y2.dev/docs/api/x402).

```
curl "https://api.y2.dev/api/v1/osint/events?limit=50" \
  --header "Authorization: Bearer $Y2_API_KEY"
```

A request without `Authorization` begins with `402 Payment Required`. Retry it with the signed payment header described in that response. Do not send bearer and x402 credentials together.

## Search regional events

`/regional` combines text, source, category, severity, region, country, time, and coordinate filters with AND semantics. Events without coordinates remain unless you request a bounding box, radius, or `requireCoordinates=true`.

```
curl --get "https://api.y2.dev/api/v1/osint/regional" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "q=port disruption" \
  --data-urlencode "sourceType=rss" \
  --data-urlencode "category=economic" \
  --data-urlencode "bbox=-10.0,35.0,40.0,65.0" \
  --data-urlencode "datetime=2026-07-01T00:00:00Z/2026-07-21T23:59:59Z" \
  --data-urlencode "limit=100"
```

`q` searches title and falls back to description substrings. `bbox` is exactly `west,south,east,north` in WGS 84 and cannot cross the antimeridian. Radius search requires all three of `nearLat`, `nearLon`, and `radiusKm`. The maximum radius is 20,000 km.

Use `datetime` for new integrations. It accepts an RFC 3339 instant or inclusive `start/end` interval. `..` creates an open boundary. The inclusive epoch-millisecond `since` and `until` parameters are deprecated and cannot be combined with `datetime`.

## Read country news

Use a two-letter country code to retrieve recent news and report observations:

```
curl "https://api.y2.dev/api/v1/osint/countries/SA/news?limit=8" \
  --header "Authorization: Bearer $Y2_API_KEY"
```

The country filter uses the observation's geographic attribution. A Saudi pipeline event can qualify for `SA`. A regional Red Sea event does not qualify merely because Saudi Arabia is mentioned or exposed to its effects. Available geographic evidence appears in `provenance.geoResolution`, including the resolution method, matched text, and related or mentioned country codes when available. These associations do not expand the country filter.

Country news includes unexpired `rss`, `gdelt`, `acled`, `news_terminal`, and `y2_report` observations, excluding seismic and weather categories. Source and expiry filters apply before the page limit, so satellite detections do not consume the news window. The default `limit` is 8 and the maximum is 20. Follow `links.next` to continue.

The API returns canonical observations with stable `obs_` IDs. The country card can deduplicate articles for display, so its headline count can differ from the API's observation count. The [News API](https://y2.dev/docs/api/news) serves a separate topic-feed cache and requires `news:read`. This country-news endpoint requires `osint:read`.

If a country-news cursor is invalid or obsolete, the API returns HTTP 400 with `VALIDATION_ERROR`. Restart without the cursor and follow the new continuation links. Integrations carrying a cursor from before the [September country-news update](https://y2.dev/docs/changelog/2026-09#more-dependable-country-news) need to restart their collection after that rollout. A scan that exceeds its read budget returns `QUERY_TOO_BROAD`. Neither error is evidence that the country has no news.

See the [endpoint reference](https://y2.dev/docs/api/reference/osint/getCountryNews) for the full response contract.

## Choose JSON, NDJSON, or GeoJSON

Representation support is operation-specific and listed on each generated reference page.

**JSON**

JSON collection responses contain `data`, `meta`, and `links`. Follow `links.next` until it is `null`.

```
curl "https://api.y2.dev/api/v1/osint/cyber-threats?limit=100" \
  --header "Authorization: Bearer $Y2_API_KEY"
```

**NDJSON**

Supported collection routes return one canonical `data` row per line. Read continuation from `X-Y2-Next-Cursor`.

```
curl "https://api.y2.dev/api/v1/osint/finint?format=ndjson&limit=100" \
  --header "Authorization: Bearer $Y2_API_KEY"
```

**GeoJSON**

Spatial routes return an RFC 7946 FeatureCollection. Coordinates are longitude-first, and the next page is the item in `links` whose `rel` is `next`.

```
curl "https://api.y2.dev/api/v1/osint/map?format=geojson&limit=200" \
  --header "Authorization: Bearer $Y2_API_KEY"
```

You can use `Accept: application/x-ndjson` or `Accept: application/geo+json` instead of `format`. Do not assume that every OSINT operation supports every representation: country briefs, country stock indices, country CII, and source status return JSON only.

## Page collections safely

JSON collections expose an opaque, filter-bound cursor through `meta.page.nextCursor` and `links.next`. Specialized representations move the cursor to `X-Y2-Next-Cursor` so their body can stay representation-native. Preserve the original filters on the next request.

The maximum `limit` depends on the operation: for example, `/map` allows 500, `/regional` allows 200, and country prediction pages allow 10. Use the generated reference instead of assuming one global maximum.

## Check source health before declaring absence

If a feed is empty or unexpectedly stale, inspect `/sources/status`:

```
curl "https://api.y2.dev/api/v1/osint/sources/status" \
  --header "Authorization: Bearer $Y2_API_KEY"
```

| Field                               | Meaning                                                                                                     |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `state`                             | `closed` normally permits fetching. `open` isolates a failing source. `half_open` is a recovery probe state |
| `failureCount`                      | Consecutive failures. A successful fetch resets it to zero                                                  |
| `lastSuccessAt`, `lastSuccessAtISO` | Last success in epoch milliseconds and RFC 3339. Nullable before any success                                |
| `lastFailureAt`, `lastFailureAtISO` | Most recent failure in both time formats                                                                    |
| `lastError`                         | Most recent provider error when available                                                                   |

Live-provider circuit breakers open after five consecutive failures and permit one probe after a five-minute cooldown. A `y2_report` row represents report-enrichment health rather than a polled provider: `open` means the newest recorded enrichment error is later than the latest success.

A healthy source does not prove completeness, and an empty endpoint does not prove that no real-world event occurred. Preserve source attribution and corroborate high-impact conclusions.

## OSINT v1 or Intel v2?

| Use OSINT v1 when you need                | Use [Intel v2](https://y2.dev/docs/api/intel) when you need |
| ----------------------------------------- | ----------------------------------------------------------- |
| Source-oriented normalized observations   | Stable entity and incident identity                         |
| Country and provider-specific surfaces    | Relationship and graph traversal                            |
| GeoJSON or NDJSON where advertised        | Sparse semantic projections and bounded relations           |
| Provider health and circuit-breaker state | Intel-specific FININT, cyber, or Explorer scopes            |

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

[Regional search](https://y2.dev/docs/api/reference/osint/listOsintRegionalEvents)

[Source status](https://y2.dev/docs/api/reference/osint/listSourceStatus)

[FININT indicators](https://y2.dev/docs/api/reference/osint/listFinintIndicators)

[Situation Room guide](https://y2.dev/docs/osint)

[Integration recipes](https://y2.dev/docs/api/integration-recipes)

[News API](https://y2.dev/docs/api/news)

[API Workbench](https://y2.dev/docs/api/workbench)
