> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consensus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get citations

> Find the papers that cite a set of seed papers, up to 20 seeds in one request. Each paper comes back in the same shape as a search result.

**Which seeds:** pass `paper_ids` (the `paper_id` on search, Thread, citations or references results), `dois`, or both. 1 to 20 in total. DOIs that match no Consensus paper come back in `unmatched_dois`.

**Several seeds:** each paper carries `seeds_touched`, how many of the seeds it cites. With the default `sort`, papers that cite more of the seeds rank first.

**Filters and order:** `year_min`, `year_max` and `cite_min` narrow the results. `sort` is `recency_weighted` (the default), `most_cited` or `most_recent`.

**Paging:** `page` starts at 0 and `page_size` defaults to 20, up to your plan's maximum. Request `next_page` until `is_end` is true. Paging reaches the first 10,000 papers.

**Cost:** 1 credit per 100 papers returned, rounded up, with a minimum of 1 per request. `credits_charged` shows what the request used.

**Access:** paid plans only. A `403` means citations aren't available to your key.

**Rate limit:** 1 request per second.

> [!WARNING]
>
> This endpoint is in beta, so its request and response schemas may change in the coming days.


## OpenAPI

````yaml /openapi.json get /v1beta/papers/citations
openapi: 3.1.0
info:
  title: Consensus API
  description: >-
    Search usage is billed in calls: one call per 100 papers returned, rounded
    up, with a minimum of 1 call per request. Usage counts against your plan's
    included monthly calls. Free plans include 30 calls per month, Pro and Teams
    plans include 500, and Deep plans include 2,000. Paid plans with an active
    metered API subscription may continue past the included limit; additional
    calls are billed at $0.05 per call. Enterprise API keys have unlimited
    access.
  version: '1.0'
servers:
  - url: https://api.consensus.app
security: []
paths:
  /v1beta/papers/citations:
    get:
      tags:
        - Citations (beta)
      summary: Get citations
      description: >-
        Find the papers that cite a set of seed papers, up to 20 seeds in one
        request. Each paper comes back in the same shape as a search result.


        **Which seeds:** pass `paper_ids` (the `paper_id` on search, Thread,
        citations or references results), `dois`, or both. 1 to 20 in total.
        DOIs that match no Consensus paper come back in `unmatched_dois`.


        **Several seeds:** each paper carries `seeds_touched`, how many of the
        seeds it cites. With the default `sort`, papers that cite more of the
        seeds rank first.


        **Filters and order:** `year_min`, `year_max` and `cite_min` narrow the
        results. `sort` is `recency_weighted` (the default), `most_cited` or
        `most_recent`.


        **Paging:** `page` starts at 0 and `page_size` defaults to 20, up to
        your plan's maximum. Request `next_page` until `is_end` is true. Paging
        reaches the first 10,000 papers.


        **Cost:** 1 credit per 100 papers returned, rounded up, with a minimum
        of 1 per request. `credits_charged` shows what the request used.


        **Access:** paid plans only. A `403` means citations aren't available to
        your key.


        **Rate limit:** 1 request per second.
      operationId: v1beta_get_papers_citations
      parameters:
        - name: paper_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            description: >-
              Seed paper ids from search, Threads, citations or references
              results (each result's paper_id). Repeat the parameter for
              several: ?paper_ids=A&paper_ids=B.
            title: Paper Ids
          description: >-
            Seed paper ids from search, Threads, citations or references results
            (each result's paper_id). Repeat the parameter for several:
            ?paper_ids=A&paper_ids=B.
        - name: dois
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
            description: >-
              Seed DOIs, with or without a https://doi.org/ or doi: prefix.
              Repeat the parameter for several. A DOI that names no Consensus
              paper comes back in unmatched_dois.
            title: Dois
          description: >-
            Seed DOIs, with or without a https://doi.org/ or doi: prefix. Repeat
            the parameter for several. A DOI that names no Consensus paper comes
            back in unmatched_dois.
        - name: year_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            description: Only papers published in or after this year.
            title: Year Min
          description: Only papers published in or after this year.
        - name: year_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            description: Only papers published in or before this year.
            title: Year Max
          description: Only papers published in or before this year.
        - name: cite_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
            description: Only papers cited at least this many times.
            title: Cite Min
          description: Only papers cited at least this many times.
        - name: sort
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CitationSort'
            description: >-
              recency_weighted: papers linked to more of the seeds first, then
              by how fast they are cited, so new papers are not buried.
              most_cited: highest citation count first. most_recent: newest
              first, most cited first within a year.
            default: recency_weighted
          description: >-
            recency_weighted: papers linked to more of the seeds first, then by
            how fast they are cited, so new papers are not buried. most_cited:
            highest citation count first. most_recent: newest first, most cited
            first within a year.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: Zero-indexed page to read.
            default: 0
            title: Page
          description: Zero-indexed page to read.
        - name: page_size
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 1
              - type: 'null'
            description: >-
              Papers per page; 20 when omitted, and at most your plan's page
              size cap.
            title: Page Size
          description: >-
            Papers per page; 20 when omitted, and at most your plan's page size
            cap.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitationsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - XApiKeyHeader: []
components:
  schemas:
    CitationSort:
      type: string
      enum:
        - recency_weighted
        - most_cited
        - most_recent
      title: CitationSort
      description: >-
        How a citation-edge read ranks a paper's citations or references.


        Like `CitationFilter`, this is both a tool and node input and the
        index-layer arg.
    CitationsResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/CitationResult'
          type: array
          title: Results
          description: >-
            The page's papers, ranked by sort. Each paper_id can seed a next
            call.
        page:
          type: integer
          title: Page
          description: The zero-indexed page returned.
        page_size:
          type: integer
          title: Page Size
          description: Papers per page actually applied to this response.
        is_end:
          type: boolean
          title: Is End
          description: >-
            True when no later page holds more papers for these seeds and
            filters. A page can hold fewer than page_size papers and still not
            be the end.
        next_page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Next Page
          description: Next zero-indexed page to request, if one is available.
        unmatched_dois:
          items:
            type: string
          type: array
          title: Unmatched Dois
          description: Requested DOIs, normalized, that name no Consensus paper.
        credits_charged:
          type: integer
          title: Credits Charged
          description: >-
            Credits this request used: one per 100 papers returned, at least
            one.
      type: object
      required:
        - results
        - page
        - page_size
        - is_end
        - credits_charged
      title: CitationsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CitationResult:
      properties:
        paper_id:
          type: string
          title: Paper Id
          description: >-
            Consensus id of the paper. Pass it to GET /v1/papers/full_text to
            read the paper's complete text when full_text_available is true.
        full_text_available:
          type: boolean
          title: Full Text Available
          description: >-
            True when the paper is open access, so GET /v1/papers/full_text can
            return its complete text.
        abstract:
          type: string
          title: Abstract
          description: Abstract of the paper.
        authors:
          items:
            type: string
          type: array
          title: Authors
          description: List of the paper's authors.
        doi:
          type: string
          title: Doi
          description: Digital Object Identifier for the document.
        journal_name:
          type: string
          title: Journal Name
          description: Publication journal of the paper.
        pages:
          type: string
          title: Pages
          description: Page range of the paper.
        publish_year:
          type: integer
          title: Publish Year
          description: Publication year of the paper.
        title:
          type: string
          title: Title
          description: Title of the paper.
        url:
          type: string
          title: Url
          description: Consensus URL for more paper details.
        volume:
          type: string
          title: Volume
          description: Journal volume of the paper.
        semantic_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Semantic Score
          description: >-
            Semantic relevance score for the paper. Only returned when
            include_semantic_score is true. The score is only returned for the
            top 50 results; it is omitted for all later results.
        citation_count:
          type: integer
          title: Citation Count
          description: Number of citations for the paper.
        study_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Study Type
          description: Study type of the paper.
        takeaway:
          anyOf:
            - type: string
            - type: 'null'
          title: Takeaway
          description: Key takeaway or summary from the paper abstract.
        publisher_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Publisher Name
          description: Publisher display name.
        full_text_chunks:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Full Text Chunks
          description: >-
            Query-relevant excerpts from the paper's full text, for open-access
            papers; only the first 20 eligible papers on each page carry them.
            Returned by default on paid plans; omitted when
            include_full_text_chunks is false.
        sjr_best_quartile:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sjr Best Quartile
          description: >-
            SCImago Journal Rank best quartile for the journal (1 = top, 4 =
            bottom).
        sample_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sample Size
          description: Number of participants or subjects in the study, when known.
        study_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Study Count
          description: >-
            Number of studies synthesized (e.g. for a meta-analysis), when
            known.
        population_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Population Type
          description: 'Study population type: ''human'', ''animal'', or ''other''.'
        is_preprint:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Preprint
          description: True when the paper is a preprint (not yet peer-reviewed).
        countries_of_study:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Countries Of Study
          description: Countries where the study was conducted, when known.
        study_duration_days:
          anyOf:
            - type: integer
            - type: 'null'
          title: Study Duration Days
          description: Study duration in days, when known.
        influential_citation_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Influential Citation Count
          description: Number of influential citations (from Semantic Scholar).
        institutions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Institutions
          description: Author institutional affiliations, when known.
        publish_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Publish Date
          description: Full publication date (YYYY-MM-DD), when known.
        institutional_access_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Institutional Access Url
          description: >-
            Link to the paper's full text through the caller's institution, via
            LibKey. Returned on paid plans when the caller has selected an
            institution in Consensus settings and LibKey has a link for the
            paper; an organization API key uses the institution of the person
            who created it. Only the first 50 results of a page carry it.
            Rolling out gradually, so not every eligible account receives it
            yet.
        seeds_touched:
          anyOf:
            - type: integer
            - type: 'null'
          title: Seeds Touched
          description: >-
            How many of the seeds this paper cites, or is cited by. Returned
            only when more than one seed was read.
      type: object
      required:
        - paper_id
        - full_text_available
        - abstract
        - authors
        - doi
        - journal_name
        - pages
        - publish_year
        - title
        - url
        - volume
        - citation_count
      title: CitationResult
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    XApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.