---
title: "List subjects and counts."
method: GET
path: "/v0.1/discovery/subjects/browse"
tags: ["discovery"]
---

# List subjects and counts.

`GET /v0.1/discovery/subjects/browse`

## Request

- Base URL: `https://platform.nypl.org/api`
- URL: `https://platform.nypl.org/api/v0.1/discovery/subjects/browse`
- Auth: none declared
- TypeScript: <https://skmtc.dev/nypl/apis/discovery-api/docs/v0.1/discovery/subjects/browse/get.ts> (a function with typed inputs; its response is checked against the schema)

Browse subjects starting by a prefex (can be a whole term or a letter)
> `/discovery/browse/subjects?search_scope=starts_with&q=M`

Look up exact subjects
> `/discovery/browse/subjects?q=Manhattan`

Or look up subjects containing a substring
> `/discovery/browse/subjects?search_scope=has&q=Africa`

## Query parameters

- `q` string
- `page` integer
- `per_page` integer
- `sort` 'relevance' | 'preferredTerm' | 'count'
- `sort_direction` 'asc' | 'desc'
- `search_scope` 'has' | 'starts_with'

## Response `200`

An array of subjects

- SubjectsResponse
  - `@type` 'subjectList'
  - `page` integer
  - `perPage` integer
  - `subjects` Subject[]
    - `preferredTerm` string: The main name of the subject.
    - `count` integer: How many bibs with this subject are in the index.
    - `uri` string: Identifier for the authority record corresponding to this subject.
    - `variants` string[]: Alternate names for this subject.
    - `narrowerTerms` string[]: More specific subjects related to this subject.
    - `broaderTerms` string[]: More general subjects related to this subject.

## Other responses

- `default`: Unexpected error

## Changes

- **2025-07-17** `7a474a7026b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nypl/apis/discovery-api/changes/v0.1/discovery/subjects/browse/get.md)

---

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