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

# List highlights

`GET /highlights`

## Request

- Base URL: `https://api.screvi.com/api/v1`
- URL: `https://api.screvi.com/api/v1/highlights`
- Auth: API key in header `X-API-Key`

Returns a paginated list of your highlights, ordered by most recent first. Includes the source/article each highlight belongs to, and any tags.

## Query parameters

- `page` integer
- `per_page` integer
- `source_id` string, uuid
- `favorite` boolean
- `tag_id` string, uuid
- `tag` string
- `updated_since` string, date-time
- `include_deleted` boolean
- `include_metadata` boolean

## Response `200`

A paginated list of highlights

- object
  - `data` Highlight[]
    - `id` string, uuid
    - `content` string: The highlight text
    - `note` string, nullable: User note attached to the highlight
    - `favorite` boolean
    - `url` string, nullable
    - `location` number, nullable: Position in the source (Kindle location, page, or offset)
    - `date` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `tags` Tag[]
      - `id` string, uuid
      - `name` string
      - `color` string, nullable
    - `source` HighlightSource
      - `id` string, uuid
      - `name` string
      - `type` 'book' | 'article' | 'tweet' | 'self' | 'podcast' | 'video' | 'custom' | 'youtube' | 'pdf'
      - `author` string, nullable
      - `image_url` string, nullable
      - `url` string, nullable
    - `metadata` object: Free-form JSON stored with the highlight. Only returned when `include_metadata=true`.
  - `pagination` Pagination
    - `page` integer
    - `per_page` integer
    - `total` integer
    - `total_pages` integer
    - `has_more` boolean

## Other responses

- `401`: Missing or invalid API key

---

[API](https://skmtc.dev/screvi/apis/screvi-public-api.md) · [All operations](https://skmtc.dev/screvi/apis/screvi-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/screvi/apis/screvi-public-api/revisions/b14be9630c5d?raw)