---
title: "Query the Intel API (v2)"
description: "Find ontology incidents, entities, signals, markets, financial indicators, disclosures, and cyber graphs"
canonical: https://y2.dev/docs/api/intel/
---

# Query the Intel API (v2)

Find ontology incidents, entities, signals, markets, financial indicators, disclosures, and cyber graphs

Intel v2 turns normalized observations into stable incidents, entities, relationships, markets, and decision signals. Use it when your integration needs to follow identity and relationships instead of processing a raw event feed.

The base URL is:

```
https://api.y2.dev/api/v2
```

Explorer investigation boards are an in-app feature. The public Intel API exposes the ontology resources that can inform an investigation, but it does not expose investigation-board CRUD endpoints.

## Choose a collection

| Goal                                                   | Endpoint                                                                 | Primary scope                                |
| ------------------------------------------------------ | ------------------------------------------------------------------------ | -------------------------------------------- |
| Find normalized incidents                              | `GET /incidents`                                                         | Depends on `category`                        |
| Search ontology entities                               | `GET /entities`                                                          | `intel:explorer`                             |
| Read a single entity                                   | `GET /entities/{entityId}`                                               | `intel:explorer`                             |
| Traverse relationships                                 | `GET /entities/{entityId}/graph`                                         | `intel:explorer`                             |
| Read workspace company financial history               | `GET /entities/{entityId}/financial-observations`                        | `intel:finint` (workspace key)               |
| Fuse cyber and market exposure for a company           | `GET /entities/{entityId}/fusion`                                        | `intel:explorer` (workspace key)             |
| Record and read evidenced claims                       | `/ledger/*` ([Ontology Ledger](https://y2.dev/docs/api/ontology-ledger)) | `ledger:read`, `ledger:write`                |
| Read prediction markets                                | `GET /markets`                                                           | `intel:finint`                               |
| Read financial indicators                              | `GET /finint`                                                            | `intel:finint`                               |
| Screen SEC filings, insider trades, and federal awards | `GET /disclosures`                                                       | `intel:disclosures`                          |
| Find extracted decision signals                        | `GET /signals`                                                           | Depends on `domain`                          |
| Traverse a cyber-focused graph                         | `GET /cyber/graph`                                                       | `intel:cyber`                                |
| Search CVEs                                            | `GET /cyber/cves`                                                        | `intel:cyber`                                |
| Read a CVE disclosure or retained revision             | `GET /cyber/cves/{cveId}`                                                | `intel:cyber`                                |
| Search threat actors                                   | `GET /cyber/actors`                                                      | `intel:cyber`                                |
| Look up a domain's DNS footprint                       | `POST /cyber/dns/lookups`                                                | `intel:cyber` (Pro and Elite, workspace key) |
| Read a domain's DNS snapshot history                   | `GET /cyber/dns/snapshots`                                               | `intel:cyber` (Pro and Elite, workspace key) |

`GET /api/v2/changes` is the durable change feed for public intelligence resources. It uses `osint:read`, not an Intel scope. See [Integration Recipes](https://y2.dev/docs/api/integration-recipes) for a checkpointed ingestion pattern.

## List incidents

Start with the narrowest category, lifecycle, severity, and time filters your application can use. `sinceMs` is a lower bound on `lastObservedAt`, expressed in Unix milliseconds.

Incident timestamps answer different questions:

| Field             | Meaning                                                  |
| ----------------- | -------------------------------------------------------- |
| `occurredAt`      | When the incident happened or is forecast to happen      |
| `firstObservedAt` | When Y2 first observed the incident                      |
| `lastObservedAt`  | When Y2 most recently observed or refreshed the incident |

A forecast incident can have an `occurredAt` value years in the future while both observation timestamps reflect when Y2 received the supporting information. Use `lastObservedAt`, not `occurredAt`, as an incremental polling watermark.

```
curl --get "https://api.y2.dev/api/v2/incidents" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "category=cyber" \
  --data-urlencode "severity=high" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=50" \
  --data-urlencode "fields[incidents]=title,severity,status,lastObservedAt"
```

List collections return `data`, `meta`, and `links`. Follow `links.next` until it is `null`. The cursor is opaque and bound to the request's filters. Limits are clamped to `1–500`.

For incremental polling, convert the largest returned `lastObservedAt` value to Unix milliseconds and pass it on the next request:

```
curl --get "https://api.y2.dev/api/v2/incidents" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "sinceMs=1786374126243" \
  --data-urlencode "fields[incidents]=title,status,occurredAt,firstObservedAt,lastObservedAt"
```

## Drill into related context

An incident or entity detail request returns its primary resource by default. Use `include` to request only the bounded related collections you need.

**Incident**

```
curl --get \
  "https://api.y2.dev/api/v2/incidents/inc_0123456789abcdef01234567" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "include=observations,entities,primaryPlace" \
  --data-urlencode "fields[incidents]=title,severity,status,lastObservedAt" \
  --data-urlencode "fields[observations]=title,severity,observedAt,geometry"
```

Supported includes are `observations`, `markets`, `entities`, `primaryPlace`, and `relatedIncidents`.

**Entity**

```
curl --get \
  "https://api.y2.dev/api/v2/entities/ent_0123456789abcdef01234567" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "include=relations,relatedEntities,incidents" \
  --data-urlencode "fields[entities]=kind,name,aliases,updatedAt"
```

Supported includes are `relations`, `relatedEntities`, `incidents`, `markets`, `observations`, `companyIdentity`, and `financialObservations`. The last two apply to organization and vendor entities. Financial observations are scoped to the key's workspace.

Sparse fieldsets use `fields[incidents]`, `fields[entities]`, `fields[markets]`, `fields[observations]`, `fields[finint]`, or `fields[signals]` as appropriate. The server always retains resource identity fields and rejects unsupported fields or includes. A request can contain at most 24 values in each projection parameter.

## Traverse a graph

Use the general entity graph after resolving an `ent_...` ID from `/entities`. Its breadth-first traversal accepts `depth=0–3`, supports a comma-separated `relationKinds` filter, and is capped at 200 nodes.

```
curl --get \
  "https://api.y2.dev/api/v2/entities/ent_0123456789abcdef01234567/graph" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "depth=2" \
  --data-urlencode "relationKinds=affects,targets,uses"
```

For a CVE, threat actor, or malware family, `/cyber/graph` offers a cyber-specific traversal. Pass at least one of `rootCveId`, `rootActorId`, or `rootMalwareFamilyId`. Its depth is limited to `1–2`.

## Follow a company across cyber and market events

Company endpoints read workspace research, so they require a workspace-bound API key and never accept x402 payment.

`GET /entities/{entityId}/financial-observations` pages through the workspace's recorded financial facts for an organization or vendor, newest recorded first. Filter with `metricKey` (an index) or `factType` (applied per page, so an empty page can still carry a next cursor). Each fact keeps its reporting period, recorded time, source provenance, and, for SEC imports, the retained JSON record pointer. History reflects what Y2 retained, not complete filing coverage.

`GET /entities/{entityId}/fusion` places cyber, market, supply-chain, and geopolitical events about the company and the parties on its exposure path on one timeline:

```
curl --get \
  "https://api.y2.dev/api/v2/entities/ent_0123456789abcdef01234567/fusion" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "windowDays=90" \
  --data-urlencode "adjacencyDays=7"
```

| Field            | Meaning                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `counterparties` | Suppliers, customers, parents, subsidiaries, and operated systems, from catalog ties or evidenced ledger claims (`provenance`) |
| `timeline`       | Dated events, newest first, each with `domain`, `path`, `provenance`, and a public `source` ID                                 |
| `undated`        | Events without a source time, kept visible instead of placed at a guessed date                                                 |
| `adjacencies`    | A market event that followed a cyber event within `adjacencyDays`. Timing, not causation                                       |
| `topics`         | Workspace topics whose subject sits on the exposure path                                                                       |
| `coverage`       | Read budgets that were reached and what each source does not cover                                                             |

See [Cyber-market fusion](https://y2.dev/docs/ontology/explanation/cyber-market-fusion) for what the view claims and what it does not.

## Screen disclosures

`GET /disclosures` lists primary-source records that companies and the federal government publish:

| `kind`                | Source                               | What one row is                                                     |
| --------------------- | ------------------------------------ | ------------------------------------------------------------------- |
| `material_event`      | SEC Form 8-K and 8-K/A               | One current report, classified by its most material item            |
| `insider_transaction` | SEC Forms 3, 4, and 5 and amendments | One Section 16 filing with up to 25 transaction lines               |
| `ownership_stake`     | SEC Schedule 13D and 13D/A           | One beneficial-ownership filing with its reporting persons          |
| `federal_award`       | USAspending.gov                      | One contract action of $5M or more, or grant action of $10M or more |

Y2 reads SEC EDGAR twice a day and USAspending once a day. Each row links to its primary record in `source.url`: the SEC filing index or the USAspending award page.

Filter with `kind`, `category`, `severity`, `entityId`, `q`, `minAmountUsd`, and `sinceMs`. `sort=amount` orders insider values or award obligations largest first and requires `kind`.

```
curl "https://api.y2.dev/api/v2/disclosures?kind=insider_transaction&category=buy&sort=amount&limit=10" \
  -H "Authorization: Bearer $Y2_API_KEY"
```

Every party is an ontology entity. Y2 matches an issuer, insider, or filer by SEC CIK and a recipient by SAM Unique Entity ID first. A new name is compared with existing entities by governed entity resolution before Y2 creates an entity, so a company that files with the SEC and receives federal contracts is one entity. A party that cannot be linked without risking a false merge has `entity: null`.

Disclosures also add relationships to the graph:

- An officer or director is `part_of` the issuer.
- A contract recipient `supplies` the awarding office. A grant's awarding office `supplies` the recipient. An office is `part_of` its department.

Each relationship records when it was first and last evidenced and cites the disclosure's observation in `provenance.observation`. Use `entityId` to list every disclosure that names a company, insider, or agency.

`occurredAt` is the event, transaction, or action date. `publishedAt` is the SEC filing date or the award action date. Both are provider calendar dates at midnight UTC.

## Read CVE disclosures

`GET /cyber/cves` keeps the entity list contract: stable `ent_...` identifiers, `data`, `meta`, `links`, cursor pagination, and `q` search. Each row adds a compact disclosure summary and links to its detail, public page, and share card. Use `fields[entities]` to select the fields your integration needs.

The `cve` summary includes source status, primary CVSS, KEV membership, EPSS, remediation status, and affected-product/reference counts. `summaryAvailable: false` means the compact summary has not been projected yet; full detail may still be available. Existing catalog attributes remain present during collection updates.

```
curl --get "https://api.y2.dev/api/v2/cyber/cves" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "q=CVE-2021-27460" \
  --data-urlencode "limit=10"

curl "https://api.y2.dev/api/v2/cyber/cves/CVE-2021-27460" \
  --header "Authorization: Bearer $Y2_API_KEY"
```

The detail contains source-specific CVSS metrics, affected products and version ranges, remediation, references, weaknesses, KEV, EPSS, SSVC, exploit references, and source retrieval times when collected. It reads the same normalized public disclosure as the Cyber UI and public page. Private workspace notes and investigations are excluded.

The detail returns `data.type: "cve_disclosure"` and the same `data.id` as the ontology entity. Its numeric dates use Unix milliseconds, matching public JSON. Summary dates and `RecordSource.retrievedAt` use RFC 3339 as in other v2 lists.

Pass `revision=<64-character SHA-256>` to retrieve a retained historical disclosure. An unknown CVE or revision returns `404`; an invalid identifier or revision returns `400`. Rejected CVEs remain readable with their status. A missing assessment or fix means the retained sources do not report one.

Both endpoints retain the `intel:cyber` scope and documented x402 access. Reading a CVE does not trigger provider collection. See [CVE disclosures](https://y2.dev/docs/osint/cve-disclosures) for collection coverage, source authority, and ontology behavior.

## Look up DNS footprints

`POST /cyber/dns/lookups` returns the DNS footprint of a domain from DNSDumpster. The footprint contains A, MX, NS, CNAME, and TXT records. Each address includes its network operator (ASN), netblock, country, reverse DNS, and HTTP and TLS banners. Send `domain`. Or send `entityId` to use the official website that Y2 records for that entity.

```
curl -X POST "https://api.y2.dev/api/v2/cyber/dns/lookups" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'
```

A snapshot younger than 14 days answers every caller with `outcome: "reused"`. A reused snapshot does not use the workspace allowance. Otherwise Y2 takes a new snapshot with `outcome: "fetched"`. A new snapshot uses one monthly DNS lookup. Pro includes 5. Elite includes 1,000. `usage` reports the allowance after the request.

A failed provider call returns the lookup to the allowance. The response is `429` or `503`. Retry after the `Retry-After` value.

Each snapshot keeps `receivedAt`, the time when the answer arrived. `truncated` is `true` when the provider has more than the 50 A records that it returned. `GET /cyber/dns/snapshots?domain=` lists stored snapshots, newest first. It never uses the allowance.

Snapshots add the domain, hosts, addresses, netblocks, and network operators to the graph. `ontology.linkedEntities` lists known organizations whose official website is the domain. See [DNS footprints in the graph](https://y2.dev/docs/ontology/explanation/dns-footprints) for each entity and relationship.

Lookups need a workspace-bound key. They are not available through x402. With the [local MCP server](https://y2.dev/docs/api/mcp-reference#openapi-tools), call `createDnsLookupV2` or `listDnsSnapshotsV2` through `y2_call_api`.

## Select the correct scope

| Scope               | Accepted operations                                                                                                                   |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `intel:explorer`    | Entities, entity details and graphs, cyber-market fusion, unfiltered incidents, and general signals                                   |
| `intel:finint`      | Markets, FININT indicators, company financial history, non-cyber categorized incidents, and markets or supply-chain signals           |
| `intel:cyber`       | Cyber graph, CVE lists and disclosures, actor lists, cyber incidents, cyber or technology signals, and DNS footprints (Pro and Elite) |
| `intel:disclosures` | SEC 8-K, Form 3/4/5, and Schedule 13D filings and federal contract and grant awards (Pro and Elite)                                   |

When `/signals` has no `domain` filter, any Intel scope is accepted. Other signal domains require `intel:explorer`. Authenticated requests can receive authorized private and workspace rows. X402 callers receive global and community rows only.

New API keys with Intel scopes require Pro or Elite. Existing Lite API keys remain valid under the current grace policy, while Lite retains its in-app Intel surfaces. See [Plans and Limits](https://y2.dev/docs/plans) for the complete product-entitlement matrix.

## Authenticate or pay per request

Intel endpoints accept a scoped key or their documented [x402 payment flow](https://y2.dev/docs/api/x402). Company financial history and fusion require a workspace-bound key because they read workspace research. A request without `Authorization` begins with `402 Payment Required`. Retry it with the signed payment header described by that endpoint. Do not send both a bearer key and x402 payment for the same request.

## Intel v2 or OSINT v1?

| Use Intel v2 when you need           | Use [OSINT v1](https://y2.dev/docs/api/osint) when you need |
| ------------------------------------ | ----------------------------------------------------------- |
| Stable entity and incident identity  | Broader normalized event feeds                              |
| Relationships and graph traversal    | Source-health and source-specific surfaces                  |
| Bounded related-resource expansion   | Country, regional, and geospatial feeds                     |
| Semantic FININT and decision signals | NDJSON or GeoJSON representations where documented          |

## Endpoint reference

[Incidents](https://y2.dev/docs/api/reference/intel/listIncidentsV2)

[Entities](https://y2.dev/docs/api/reference/intel/listEntitiesV2)

[Markets](https://y2.dev/docs/api/reference/intel/listMarketsV2)

[FININT](https://y2.dev/docs/api/reference/intel/listFinintIntelV2)

[Signals](https://y2.dev/docs/api/reference/intel/listSignalsV2)

[Cyber graph](https://y2.dev/docs/api/reference/intel/getCyberGraphV2)

[CVE search](https://y2.dev/docs/api/reference/intel/listCVEsV2)

[CVE disclosure](https://y2.dev/docs/api/reference/intel/getCVEDisclosureV2)

[Company financial history](https://y2.dev/docs/api/reference/intel/listCompanyFinancialObservationsV2)

[Cyber-market fusion](https://y2.dev/docs/api/reference/intel/getEntityFusionV2)

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

[Authentication](https://y2.dev/docs/api/authentication)

[OpenAPI](https://y2.dev/docs/api/openapi)

[Agent integration context](https://y2.dev/docs/api/agentic-dx)
