---
title: "List highlights"
method: GET
path: "/v1/highlights"
tags: ["Highlights"]
---

# List highlights

`GET /v1/highlights`

Retrieve all highlights in your workspace. Highlights are selected passages of text (or time ranges in audio/video transcripts) within data entries that have been marked as significant during qualitative analysis. They can be tagged with one or more tags to categorize findings.

Results can be filtered by project, tag, specific highlight ID, creation date, or update date. **Only one** of `project_id`, `tag_id`, or `highlight_id` can be used per request. Results are sortable by creation date and are paginated.

## Query parameters

- `page` object
  - `start_cursor` string
  - `limit` integer, nullable
- `sort` union
  - 'created_at:asc' | 'created_at:desc'
  - string[]
- `filter` object
  - `created_at` object — Filter results based on dates. When passing in operators, the operator pairs are mutually exclusive. For example, you cannot send both `gt` and `gte` in the same request.
    - `gt` string, date-time, nullable — Great than operator
    - `gte` string, date-time, nullable — Great than or equal to operator
    - `lt` string, date-time, nullable — Less than operator
    - `lte` string, date-time, nullable — Less than or equal operator
  - `updated_at` object — Filter results based on dates. When passing in operators, the operator pairs are mutually exclusive. For example, you cannot send both `gt` and `gte` in the same request.
    - `gt` string, date-time, nullable — Great than operator
    - `gte` string, date-time, nullable — Great than or equal to operator
    - `lt` string, date-time, nullable — Less than operator
    - `lte` string, date-time, nullable — Less than or equal operator
  - `project_id` union — Unique identifier(s) of the associated project(s)
    - string
    - string[]
  - `highlight_id` union — Unique identifier(s) of the associated highlight(s)
    - string
    - string[]
  - `tag_id` union — Unique identifier(s) for associated tag(s)
    - string
    - string[]

## Response `200`

200

- object
  - `data` object[], required
    - `id` string, required
    - `url` string, nullable — The URL of the parent note containing this highlight in the Dovetail web app. This field is experimental and may change without notice.
    - `note_id` string, nullable, required
    - `tags` object[], required
      - `id` string, required
      - `title` string, required
    - `text` string, nullable, required
    - `type` 'highlight', required
    - `start_time` number, nullable, required
    - `end_time` number, nullable, required
    - `created_at` string, required
    - `updated_at` string, required
  - `page` object, required
    - `total_count` number, required — Total number of items matching the query.
    - `has_more` boolean, required — Whether there are more items beyond the current page.
    - `next_cursor` string, nullable, required — Cursor to pass as `page[start_cursor]` to fetch the next page. Null when there are no more results.

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `422` — 422
- `429` — 429
- `500` — 500

---

[API](https://skmtc.net/dovetail/apis/dovetail-public-api.md) · [All operations](https://skmtc.net/dovetail/apis/dovetail-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dovetail/dovetail-public-api/versions/4107f5fdf8b2/schema)