---
title: "List works"
method: GET
path: "/works"
tags: ["Works"]
---

# List works

`GET /works`

Get a list of scholarly works with optional filtering, searching, sorting, and pagination. Works include journal articles, books, datasets, theses, and more.

## Query parameters

- `filter` string
- `sort` string
- `group_by` string
- `search` string
- `per_page` integer
- `page` integer
- `cursor` string
- `sample` integer
- `select` string
- `api_key` string, required

## Response `200`

Successful response

- WorksListResponse
  - `meta` Meta — Metadata about the query results
    - `count` integer — Total number of results matching the query
    - `db_response_time_ms` integer — Database response time in milliseconds
    - `page` integer — Current page number
    - `per_page` integer — Number of results per page
    - `next_cursor` string — Cursor for the next page (when using cursor pagination)
    - `groups_count` integer, nullable — Number of groups when using group_by
    - `cost_usd` number — Cost of this request in USD
  - `results` Work[]
    - `id` string — The OpenAlex ID for this work.
    - `doi` string, nullable — The DOI for the work. This is the Canonical External ID for works.
    - `title` string, nullable — The title of this work.
    - `display_name` string — Same as `title`. Included for consistency with other entities.
    - `publication_year` integer, nullable — The year this work was published.
    - `publication_date` string, date, nullable — The day when this work was published (ISO 8601 format).
    - `type` string — The type of the work. Common values: `article`, `book`, `dataset`, `preprint`, `dissertation`, `book-chapter`.
    - `language` string, nullable — [Language](/api-reference/languages) in ISO 639-1 format
    - `cited_by_count` integer — The number of citations to this work.
    - `is_retracted` boolean — True if this work has been retracted (from Retraction Watch database).
    - `is_paratext` boolean — True if this work is paratext (e.g., front cover, table of contents).
    - `primary_location` Location — Where a work is hosted
      - `is_oa` boolean — Whether this location provides open access
      - `landing_page_url` string, nullable — URL to the landing page
      - `pdf_url` string, nullable — Direct URL to PDF
      - `source` DehydratedSource — [Dehydrated Source](/api-reference/sources#the-dehydratedsource-object) — reduced-field version used in nested contexts
        - `id` string
        - `display_name` string
        - `issn_l` string, nullable
        - `issn` string[], nullable
        - `is_oa` boolean
        - `is_in_doaj` boolean
        - `is_core` boolean
        - `host_organization` string, nullable
        - `host_organization_name` string, nullable
        - `host_organization_lineage` string[]
        - `type` string — The [source type](/api-reference/source-types)
      - `license` string, nullable — The [license](/api-reference/licenses) (e.g., cc-by)
      - `license_id` string, nullable
      - `version` 'publishedVersion' | 'acceptedVersion' | 'submittedVersion', nullable — Version of the work at this location
      - `is_accepted` boolean
      - `is_published` boolean
    - `locations` Location[] — List of Location objects describing all unique places where this work lives.
      - `is_oa` boolean — Whether this location provides open access
      - `landing_page_url` string, nullable — URL to the landing page
      - `pdf_url` string, nullable — Direct URL to PDF
      - `source` DehydratedSource — [Dehydrated Source](/api-reference/sources#the-dehydratedsource-object) — reduced-field version used in nested contexts
        - `id` string
        - `display_name` string
        - `issn_l` string, nullable
        - `issn` string[], nullable
        - `is_oa` boolean
        - `is_in_doaj` boolean
        - `is_core` boolean
        - `host_organization` string, nullable
        - `host_organization_name` string, nullable
        - `host_organization_lineage` string[]
        - `type` string — The [source type](/api-reference/source-types)
      - `license` string, nullable — The [license](/api-reference/licenses) (e.g., cc-by)
      - `license_id` string, nullable
      - `version` 'publishedVersion' | 'acceptedVersion' | 'submittedVersion', nullable — Version of the work at this location
      - `is_accepted` boolean
      - `is_published` boolean
    - `best_oa_location` Location — Where a work is hosted
      - `is_oa` boolean — Whether this location provides open access
      - `landing_page_url` string, nullable — URL to the landing page
      - `pdf_url` string, nullable — Direct URL to PDF
      - `source` DehydratedSource — [Dehydrated Source](/api-reference/sources#the-dehydratedsource-object) — reduced-field version used in nested contexts
        - `id` string
        - `display_name` string
        - `issn_l` string, nullable
        - `issn` string[], nullable
        - `is_oa` boolean
        - `is_in_doaj` boolean
        - `is_core` boolean
        - `host_organization` string, nullable
        - `host_organization_name` string, nullable
        - `host_organization_lineage` string[]
        - `type` string — The [source type](/api-reference/source-types)
      - `license` string, nullable — The [license](/api-reference/licenses) (e.g., cc-by)
      - `license_id` string, nullable
      - `version` 'publishedVersion' | 'acceptedVersion' | 'submittedVersion', nullable — Version of the work at this location
      - `is_accepted` boolean
      - `is_published` boolean
    - `open_access` OpenAccess — Open access information
      - `is_oa` boolean — Whether this work is open access
      - `oa_status` 'diamond' | 'gold' | 'hybrid' | 'bronze' | 'green' | 'closed' — Open access status
      - `oa_url` string, nullable — Best open access URL
      - `any_repository_has_fulltext` boolean — Whether any repository has the full text
    - `authorships` Authorship[] — List of Authorship objects representing authors and their institutions. Limited to the first 100 authors. Each authorship includes `author`, `institutions`, `author_position`, `is_corresponding`, and other fields.
      - `author_position` 'first' | 'middle' | 'last' — Position in author list
      - `author` DehydratedAuthor — [Dehydrated Author](/api-reference/authors#the-dehydratedauthor-object) — reduced-field version used in nested contexts
        - `id` string
        - `display_name` string
        - `orcid` string, nullable
      - `institutions` DehydratedInstitution[] — [Dehydrated institutions](/api-reference/institutions#the-dehydratedinstitution-object)
        - `id` string
        - `display_name` string
        - `ror` string, nullable
        - `country_code` string, nullable — [Country](/api-reference/countries) code
        - `type` string — The [institution type](/api-reference/institution-types)
        - `lineage` string[]
      - `countries` string[] — Country codes of affiliations
      - `is_corresponding` boolean — Whether this is the corresponding author
      - `raw_author_name` string — Author name as it appears in the work
      - `raw_affiliation_strings` string[]
    - `ids` object — External identifiers: `openalex`, `doi`, `mag`, `pmid`, `pmcid`.
      - `openalex` string
      - `doi` string
      - `mag` integer
      - `pmid` string
      - `pmcid` string
    - `biblio` object — Bibliographic info: `volume`, `issue`, `first_page`, `last_page`.
      - `volume` string, nullable
      - `issue` string, nullable
      - `first_page` string, nullable
      - `last_page` string, nullable
    - `abstract_inverted_index` object, nullable — The abstract as an inverted index (word positions). OpenAlex doesn't include plaintext abstracts due to legal constraints. Use the `has_abstract` filter to get works with or without abstracts.
    - `referenced_works` string[] — OpenAlex IDs for works that this work cites.
    - `referenced_works_count` integer — The number of works that this work cites.
    - `related_works` string[] — OpenAlex IDs for works related to this work (computed algorithmically).
    - `topics` WorkTopic[] — List of up to 3 Topics for this work, each with a relevance score.
      - `id` string
      - `display_name` string
      - `score` number
      - `subfield` object — The parent [subfield](/api-reference/subfields)
        - `id` string
        - `display_name` string
      - `field` object — The parent [field](/api-reference/fields)
        - `id` string
        - `display_name` string
      - `domain` object — The parent [domain](/api-reference/domains)
        - `id` string
        - `display_name` string
    - `primary_topic` WorkTopic
      - `id` string
      - `display_name` string
      - `score` number
      - `subfield` object — The parent [subfield](/api-reference/subfields)
        - `id` string
        - `display_name` string
      - `field` object — The parent [field](/api-reference/fields)
        - `id` string
        - `display_name` string
      - `domain` object — The parent [domain](/api-reference/domains)
        - `id` string
        - `display_name` string
    - `keywords` WorkKeyword[] — Keywords identified based on the work's topics, with relevance scores.
      - `id` string
      - `display_name` string
      - `score` number
    - `funders` DehydratedFunder[] — Dehydrated Funder objects representing the funders of this work.
      - `id` string
      - `display_name` string
      - `ror` string, nullable
    - `awards` Award[] — Dehydrated Award objects representing grants associated with this work.
      - `id` string
      - `display_name` string
      - `funder_award_id` string
      - `funder_id` string
      - `funder_display_name` string
      - `doi` string, nullable
    - `fwci` number, nullable — Field-weighted Citation Impact, calculated as citations received / citations expected.
    - `citation_normalized_percentile` object, nullable — Percentile of citation count normalized by work type, year, and subfield. Includes `value`, `is_in_top_1_percent`, `is_in_top_10_percent`.
      - `value` number
      - `is_in_top_1_percent` boolean
      - `is_in_top_10_percent` boolean
    - `cited_by_percentile_year` object, nullable — Percentile rank compared to other works published in the same year. Contains `min` and `max`.
      - `min` integer
      - `max` integer
    - `counts_by_year` object[] — `cited_by_count` for each of the last ten years.
      - `year` integer
      - `cited_by_count` integer
    - `sustainable_development_goals` object[] — UN Sustainable Development Goals relevant to this work, with prediction scores.
      - `id` string
      - `display_name` string
      - `score` number
    - `mesh` object[] — MeSH tags for works found in PubMed.
      - `descriptor_ui` string
      - `descriptor_name` string
      - `qualifier_ui` string
      - `qualifier_name` string
      - `is_major_topic` boolean
    - `indexed_in` string[] — Sources this work is indexed in. Values: `arxiv`, `crossref`, `doaj`, `pubmed`.
    - `has_content` object, nullable — Information about downloadable full-text content:
      - `pdf` boolean
      - `grobid_xml` boolean
    - `content_url` string, nullable — URL for downloading full-text content. Only present when `has_content.pdf` or `has_content.grobid_xml` is true.
    - `created_date` string, date — When this work was added to OpenAlex (ISO 8601 date).
    - `updated_date` string, date-time — When this work was last updated (ISO 8601 datetime).
  - `group_by` GroupByResult[]
    - `key` string — The group key value
    - `key_display_name` string — Human-readable name for the key
    - `count` integer — Number of results in this group

## Other responses

- `400` — Bad request - invalid parameters
- `403` — Forbidden - invalid ID format
- `429` — Rate limit exceeded

---

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