Retrieve Reports through the API

Use the Reports API to retrieve published intelligence generated for profiles. Start with compact report metadata, then request only the representation or extracted artifact your integration needs.

Choose a representation

Required scopes

The audio operation also depends on audio entitlement and an available recording. Every Report operation supports x402 pay-per-request as an alternative to a bearer key.

List reports

For a bearer-key request without profileId, Y2 lists reports newest first across the active profiles subscribed in that key's user or workspace context.

curl --get "https://api.y2.dev/api/v1/reports" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "limit=20"

To target one profile, pass its canonical prf_... ID:

curl --get "https://api.y2.dev/api/v1/reports" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "profileId=$PROFILE_ID" \
  --data-urlencode "limit=20"

The endpoint supports only profileId, limit, cursor, and format; it does not provide a date range filter. limit defaults to 20 and is capped at 100.

JSON pages return data, meta, and links. Follow links.next until it is null. For NDJSON, send format=ndjson or Accept: application/x-ndjson; each line is one compact report and the next cursor is in X-Y2-Next-Cursor.

Read compact report metadata

curl "https://api.y2.dev/api/v1/reports/$REPORT_ID" \
  --header "Authorization: Bearer $Y2_API_KEY"

The default response contains the canonical rpt_... and prf_... IDs, topic, summary, published timestamps, language, signal and graph counts, audio availability, profile identity, and links to each representation. It does not include the full report body or full source rows by default.

An authenticated detail or subresource request must be subscribed to the report's profile. A missing report returns 404; an authenticated key without that subscription returns 403.

Expand structured JSON

Use the comma-separated include parameter to embed bounded related data.

curl --get "https://api.y2.dev/api/v1/reports/$REPORT_ID" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "include=content,sources,signals"

view=agent is shorthand for content,sources,signals. It does not add the ontology graph or audio representation.

Choose Markdown or plain text

curl "https://api.y2.dev/api/v1/reports/$REPORT_ID" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --header "Accept: text/markdown"

Use Markdown for grounded agents and publishing pipelines. Use /text when the consumer cannot render markup or needs reading-time metadata.

Retrieve signals or the report graph

The subresources avoid transferring the full report body:

curl "https://api.y2.dev/api/v1/reports/$REPORT_ID/signals" \
  --header "Authorization: Bearer $Y2_API_KEY"

curl "https://api.y2.dev/api/v1/reports/$REPORT_ID/graph" \
  --header "Authorization: Bearer $Y2_API_KEY"

Signals include decision fields, confidence, time horizon, normalized subjects, entity links when resolved, tags, and cited sources. Reports created before signal extraction return an empty signals array.

The graph is a bounded snapshot extracted from that report, not a live traversal of the full Intel ontology. It contains report-local nodes, relationships, incident anchors, citations, and counts. Reports created before graph extraction return graph: null and zero counts.

Retrieve narration or TTS text

Request audio metadata with reports:audio:

curl "https://api.y2.dev/api/v1/reports/$REPORT_ID/audio" \
  --header "Authorization: Bearer $Y2_API_KEY"

The JSON body contains the MP3 URL, duration, formatted duration, media type, and file size when known. To redirect directly to the CDN asset, pass redirect=true or send an Accept header that contains an audio media type. The redirect is 302, and the redirect response can be cached for 24 hours. A report without audio returns 404 NO_AUDIO.

/audio-text requires reports:read, not reports:audio. It returns the exact preprocessing path used for narration, including pronunciation normalization and applicable profile branding:

curl "https://api.y2.dev/api/v1/reports/$REPORT_ID/audio-text" \
  --header "Authorization: Bearer $Y2_API_KEY"

The duration fields on this endpoint are estimates based on character count; they are not measured audio duration.