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

# Get a patent family by id

> One patent family with its members, recorded ownership changes, prosecution and maintenance events, and the statutory term computed from the earliest nonprovisional filing (no term adjustments or extensions). Returns `404 not_found` for an unknown id.



## OpenAPI

````yaml /openapi.json get /v1/patents/{family_id}
openapi: 3.1.0
info:
  title: Pav Enterprise API
  description: >-
    Read-only `/v1` API over Pav's biopharma dataset: drug programs, companies,
    clinical trials, deals, patent families, FDA records, a change feed, and
    dataset stats.


    Authenticate every request with a Pav API key as a bearer token:
    `Authorization: Bearer <api_key>`. Mint a key in [Pav developer
    settings](https://app.pav.bio/settings/developer).


    All endpoints are `GET` and return JSON. List endpoints return a `{ data,
    pagination }` envelope. Pass `q=` to run relevance-ranked search that
    matches meaning as well as exact words; omit it for a filtered, paginated
    listing. Errors return `{ error: { code, message, request_id } }`.
  version: 1.2.0
servers:
  - url: https://api.pav.bio
    description: Production
  - url: /
    description: This server
security: []
tags:
  - name: programs
    description: >-
      Search and filter drug pipeline assets by company, indication, target,
      modality, phase, or free text. Includes get-by-id, similar-programs, and
      facet autocomplete.
  - name: companies
    description: >-
      Tracked biopharma companies and their pipeline ownership. List a company's
      programs and change history.
  - name: trials
    description: >-
      Search clinical trials — ClinicalTrials.gov records plus Pav
      program/company links. Relevance-ranked search when `q=` is set; filtered
      browse otherwise.
  - name: deals
    description: >-
      Biopharma deals (M&A, licensing, collaborations, options, joint ventures)
      from SEC filings and press releases, with lifecycle state, headline
      economics, and source documents.
  - name: patents
    description: >-
      US patent families from USPTO with owners linked to Pav companies, member
      applications, ownership history, and statutory term.
  - name: fda
    description: >-
      FDA records with applicants linked to Pav companies: Orange Book products,
      patents and exclusivities, Purple Book biologics, orphan designations,
      warning letters, and recalls.
  - name: changes
    description: >-
      Detected pipeline movement events per company — added and removed assets
      and phase changes — with before/after phase and detection time.
  - name: stats
    description: High-level dataset counts and facet coverage.
paths:
  /v1/patents/{family_id}:
    get:
      tags:
        - patents
      summary: Get a patent family by id
      description: >-
        One patent family with its members, recorded ownership changes,
        prosecution and maintenance events, and the statutory term computed from
        the earliest nonprovisional filing (no term adjustments or extensions).
        Returns `404 not_found` for an unknown id.
      operationId: get_patent_family
      parameters:
        - name: family_id
          in: path
          required: true
          schema:
            type: string
            maxLength: 64
            pattern: ^[A-Za-z0-9_-]+$
            description: Pav patent family id.
            examples:
              - '62662313'
            title: Family Id
          description: Pav patent family id.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatentFamilyDetail'
        '401':
          description: Missing or invalid API key (`unauthorized`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Unknown id or route (`not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: Invalid parameter (`validation_error`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded (`rate_limited`); honor `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - EnterpriseApiKey: []
components:
  schemas:
    PatentFamilyDetail:
      properties:
        family_id:
          type: string
          title: Family Id
          description: Pav patent family identifier.
          examples:
            - '62662313'
        representative_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Representative Title
          description: Representative title.
        member_count:
          type: integer
          title: Member Count
          description: Applications in the family.
        granted_count:
          type: integer
          title: Granted Count
          description: Granted members.
        pending_count:
          type: integer
          title: Pending Count
          description: Pending members.
        earliest_priority_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Earliest Priority Date
          description: Earliest priority date.
        earliest_filing_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Earliest Filing Date
          description: Earliest member filing.
        latest_grant_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Latest Grant Date
          description: Most recent grant.
        latest_status_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Latest Status Date
          description: Most recent status change.
        has_live_member:
          type: boolean
          title: Has Live Member
          description: True when any member is pending or in force.
        owner_names:
          items:
            type: string
          type: array
          title: Owner Names
          description: >-
            Owners of the live members; for a lapsed family, owners across all
            members.
        owner_source:
          type: string
          enum:
            - live_members
            - all_members
            - none
          title: Owner Source
          description: Which members `owner_names` was read from.
        owner_is_split:
          type: boolean
          title: Owner Is Split
          description: True when live members have different owners.
        companies:
          items:
            $ref: '#/components/schemas/PatentCompany'
          type: array
          title: Companies
          description: Owners linked to Pav companies.
        has_open_security_interest:
          type: boolean
          title: Has Open Security Interest
          description: True when any member carries an open security interest.
        latest_maintenance_fee_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Latest Maintenance Fee Date
          description: Most recent maintenance-fee payment on any member.
        statutory_term_start:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Statutory Term Start
          description: >-
            Earliest nonprovisional filing the family claims (35 USC 154(a)(2)).
            Null when an ancestor's filing date is unknown.
        statutory_term_end:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Statutory Term End
          description: >-
            `statutory_term_start` plus 20 years. Term adjustments and
            extensions are not applied.
        cpc_codes:
          items:
            type: string
          type: array
          title: Cpc Codes
          description: Most-used CPC codes across members.
        members:
          items:
            $ref: '#/components/schemas/PatentFamilyDetailMember'
          type: array
          title: Members
          description: Member applications.
        ownership:
          items:
            $ref: '#/components/schemas/PatentOwnershipEvent'
          type: array
          title: Ownership
          description: Recorded conveyances, newest first.
        events:
          items:
            $ref: '#/components/schemas/PatentProsecutionEvent'
          type: array
          title: Events
          description: Prosecution and maintenance events, newest first (capped).
        events_total:
          type: integer
          title: Events Total
          description: Uncapped count of `events`.
      type: object
      required:
        - family_id
        - member_count
        - granted_count
        - pending_count
        - has_live_member
        - owner_source
        - owner_is_split
        - has_open_security_interest
        - events_total
      title: PatentFamilyDetail
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: Error detail. Present only on 4xx/5xx responses.
      required:
        - error
      title: ErrorEnvelope
      type: object
    PatentCompany:
      properties:
        company_id:
          type: integer
          title: Company Id
          description: Durable Pav company identifier.
          examples:
            - 137
        short_name:
          type: string
          title: Short Name
          description: Company slug.
          examples:
            - johnson_and_johnson
        name:
          type: string
          title: Name
          description: Company display name.
          examples:
            - Johnson & Johnson
      type: object
      required:
        - company_id
        - short_name
        - name
      title: PatentCompany
    PatentFamilyDetailMember:
      properties:
        application_number:
          type: string
          title: Application Number
          description: USPTO application number.
          examples:
            - '17076912'
        patent_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Patent Number
          description: Granted patent number; null until granted.
        publication_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Publication Number
          description: Pre-grant publication number.
        role:
          type: string
          title: Role
          description: Member's place in the family (root, continuation, ...).
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Application title.
        application_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Application Type
          description: USPTO application type.
        filing_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Filing Date
          description: Filing date.
        grant_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Grant Date
          description: Grant date.
        status_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Description
          description: Current USPTO status.
        status_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Status Date
          description: Date of the current status.
        is_dead:
          type: boolean
          title: Is Dead
          description: True when the application is abandoned or expired.
        cpc_codes:
          items:
            type: string
          type: array
          title: Cpc Codes
          description: CPC classification codes.
        status_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Code
          description: USPTO status code.
        depth:
          type: integer
          title: Depth
          description: Distance from the family root.
        owner_names:
          items:
            type: string
          type: array
          title: Owner Names
          description: Member's current owners.
        has_open_security_interest:
          type: boolean
          title: Has Open Security Interest
          description: >-
            True when an open security interest (lien) is recorded on this
            member.
      type: object
      required:
        - application_number
        - role
        - is_dead
        - depth
        - has_open_security_interest
      title: PatentFamilyDetailMember
    PatentOwnershipEvent:
      properties:
        recorded_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Recorded Date
          description: USPTO recordation date.
        conveyance_kind:
          type: string
          title: Conveyance Kind
          description: Conveyance type (assignment, security interest, ...).
        conveyance_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Conveyance Text
          description: Conveyance as recorded.
        assignors:
          items:
            type: string
          type: array
          title: Assignors
          description: Conveying parties.
        assignees:
          items:
            type: string
          type: array
          title: Assignees
          description: Receiving parties.
        application_numbers:
          items:
            type: string
          type: array
          title: Application Numbers
          description: Members the conveyance was recorded on.
      type: object
      required:
        - conveyance_kind
      title: PatentOwnershipEvent
    PatentProsecutionEvent:
      properties:
        event_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Event Date
          description: Event date.
        application_number:
          type: string
          title: Application Number
          description: Member application number.
        patent_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Patent Number
          description: Member patent number, if granted.
        event_code:
          type: string
          title: Event Code
          description: USPTO event code.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Event description.
      type: object
      required:
        - application_number
        - event_code
      title: PatentProsecutionEvent
    ErrorBody:
      properties:
        code:
          description: >-
            Stable, machine-readable error code (e.g. `unauthorized`,
            `not_found`, `validation_error`, `error`).
          examples:
            - not_found
          title: Code
          type: string
        message:
          description: Human-readable explanation of the error.
          examples:
            - program 999999 not found
          title: Message
          type: string
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Correlation id echoed in the `X-Request-ID` response header. Quote
            it when contacting Pav support about a failed request.
          examples:
            - 3f2b9c1d8a7e4f6b9c0d1e2f3a4b5c6d
          title: Request Id
      required:
        - code
        - message
      title: ErrorBody
      type: object
  securitySchemes:
    EnterpriseApiKey:
      type: http
      description: >-
        Use a personal or organization Pav API key from Pav developer settings.
        Send it as Authorization: Bearer <api_key>.
      scheme: bearer
      bearerFormat: Pav API key

````