---
title: "summarize columns"
method: GET
path: "/datasets/{id}/summary"
tags: ["Dataset CRUD"]
---

# summarize columns

`GET /datasets/{id}/summary`

## Request

- Base URL: `https://api.riveterhq.com/v1`
- URL: `https://api.riveterhq.com/v1/datasets/{id}/summary`
- Auth: HTTP bearer

Per-column counts over every row of the dataset, without the rows: for an output column, its cells by state (`pending`, `stale`, `failed`, `not_found`, `ok`, `manual`; a fill in flight shows on [GET /datasets/{id}](#tag/dataset-crud/get/datasets/{id}) `runs`, its cells still count under the state they hold) and its most common values; for an input column, the rows with a value and its most common values. `values` holds the `top_values` most common (default 20, max 100) as `{ value, count }`; `distinct_values` and `filled` count every value. A string value longer than 200 characters is cut in `values`. `columns` picks the columns; absent, every column is summarized. Built with one aggregate query per column, so a 10,000-row dataset answers in well under a second.

## Path parameters

- `id` string, required

## Query parameters

- `columns` string
- `top_values` integer

## Response `200`

The summary

- DatasetSummary
  - `row_count` integer
  - `columns` DatasetColumnSummary[]
    - `name` string
    - `kind` 'input' | 'output'
    - `states` object: Output columns only — the column's cells by state over every row (`running` cells count under the state they hold; the fill in flight is on the dataset's `runs`)
      - `pending` integer
      - `stale` integer
      - `failed` integer
      - `not_found` integer
      - `ok` integer
      - `manual` integer
    - `filled` integer: Rows whose cell (or input value) holds a value
    - `distinct_values` integer: Distinct values among the filled rows
    - `values` object[]: The most common values, most common first, at most `top_values` of them
      - `value` unknown
      - `count` integer

## Other responses

- `400`: The request is malformed or names a conflicting parameter combination
- `401`: Missing or invalid API key (`request_status` body — see the AuthError schema)
- `403`: The API key's account may not access this resource or endpoint (`forbidden`), or the account has not migrated to Datasets yet (`feature_not_enabled` — open Datasets in the app and click "Migrate to Datasets")
- `404`: No resource with that id on this account

## Changes

- **2026-11-13** `fac56b649559`: 2 info
  - api tag `Dataset CRUD` added
  - api tag `Datasets` removed
- **2026-10-30** `dcb4d45ade1a`: 6 info
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `400` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `403` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `404` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/upfront` to the response with the `400` status
  - …2 more
- **2026-10-30** `9db88e317ebe`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/riveterhq/apis/riveter-api/changes/datasets/:id/summary/get.md)

---

[API](https://skmtc.dev/riveterhq/apis/riveter-api.md) - [All operations](https://skmtc.dev/riveterhq/apis/riveter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/riveterhq/apis/riveter-api/revisions/fac56b649559?raw)