# Global Reports

> Create, edit, and read saved cross-run reports programmatically


A **Global Report** is a named, user- (or agent-) curated view over the canonical
dataset: one tab per entity with an ordered column selection. The report stores
only its definition — every read recomputes fresh rows from the latest data
(with a short server-side cache), so a report is always current.

Auth as everywhere: `Authorization: Bearer ds_live_...`. Reads need
`reports:read`, writes `reports:write` (both in the Agent preset). Deleting a
report deletes a view definition — never researched data.

## Discover the column vocabulary first

```bash
curl -s $BASE_URL/v1/reports/columns -H "Authorization: Bearer $DEEPSIEVE_API_KEY"
```

Returns the selectable columns per entity (own columns + relationship pill
columns). Like everything Blueprint-shaped: discover, don't guess.

## Create

```bash
curl -s -X POST $BASE_URL/v1/reports \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Vendor shortlist",
       "config": {"tabs": [{"id": "t1", "name": "Companies",
                            "entity_key": "companies",
                            "columns": ["name", "hq_city", "funding_total"]}]}}'
```

Invalid entities/columns are rejected with a typed 400 pointing back at
`/v1/reports/columns`.

## Read, update, delete

```bash
curl -s $BASE_URL/v1/reports -H "Authorization: Bearer $DEEPSIEVE_API_KEY"          # list
curl -s $BASE_URL/v1/reports/{id} -H "Authorization: Bearer $DEEPSIEVE_API_KEY"     # definition
curl -s -X PATCH $BASE_URL/v1/reports/{id} -H "Authorization: Bearer $DEEPSIEVE_API_KEY" \
  -H "Content-Type: application/json" -d '{"name": "Renamed"}'                       # update
curl -s -X DELETE $BASE_URL/v1/reports/{id} -H "Authorization: Bearer $DEEPSIEVE_API_KEY"
```

## Read a tab's data

```bash
curl -s $BASE_URL/v1/reports/{id}/tabs/{tab_id}/data \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY"
```

Fresh cross-run rows for that tab's entity, with the same per-cell evidence
the UI shows. (The full column payload is returned; the tab's column
selection defines the curated view in the app and its exports.) Free-preview workspaces are row-capped here
exactly as on every other read surface.

For raw entity access with sync cursors, use [Dataset sync](/developers/dataset-sync)
instead — reports are for curated, shareable views.