---
title: "Retrieve Reports through the API"
description: "List published reports and choose compact JSON, Markdown, text, signals, graph, or audio"
canonical: https://y2.dev/docs/api/reports/
---

# Retrieve Reports through the API

List published reports and choose compact JSON, Markdown, text, signals, graph, or audio

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

| Consumer                 | Representation              |
| ------------------------ | --------------------------- |
| Agent                    | Markdown with cited sources |
| Application              | Compact or expanded JSON    |
| Analytics workflow       | Signals or graph            |
| Human reader or listener | Plain text or audio         |

## Required scopes

| Operation                                                                     | Bearer scope    |
| ----------------------------------------------------------------------------- | --------------- |
| List, detail, Markdown, plain text, signals, graph, and TTS-preprocessed text | `reports:read`  |
| Audio metadata or CDN redirect                                                | `reports:audio` |

The audio operation also depends on audio entitlement and an available recording. Every Report operation supports [x402 pay-per-request](https://y2.dev/docs/api/x402) 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.

x402 list requests need a profile ID

An anonymous x402 caller has no subscription context, so `profileId` is required for `GET /reports`. Single-report and subresource calls identify the resource with `reportId`.

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 report and profile IDs, topic, summary, timestamps, and language. It also includes signal and graph counts, audio availability, profile details, and representation links. 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.

| Include   | Added field                                                                 |
| --------- | --------------------------------------------------------------------------- |
| `content` | `content.markdown` and its media type                                       |
| `sources` | Canonical source records with `src_...` IDs and available attribution       |
| `signals` | Report-local emergent decision signals                                      |
| `graph`   | Report-local ontology nodes, edges, incidents, and citations when available |
| `audio`   | Audio representation metadata or `null`                                     |

```
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

**Markdown**

Request the canonical stored report representation:

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

`format=markdown` is equivalent. This returns the report body directly, not a JSON envelope.

**Plain text**

Request content with HTML stripped:

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

**Text metrics**

Omit `Accept: text/plain` to receive JSON with `text`, `wordCount`, and an estimated `readingTimeMinutes` at approximately 200 words per minute.

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

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.

Reports, summaries, signals, and ontology graphs are synthesized intelligence. Preserve source URLs and confidence fields, and verify high-impact conclusions against primary evidence.

[List reports](https://y2.dev/docs/api/reference/reports/listReports)

[Get a report](https://y2.dev/docs/api/reference/reports/getReport)

[Get report signals](https://y2.dev/docs/api/reference/reports/getReportSignals)

[Get report graph](https://y2.dev/docs/api/reference/reports/getReportGraph)

[Profiles API](https://y2.dev/docs/api/profiles)

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

[Audio guide](https://y2.dev/docs/audio)

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