> ## 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.

# List pipeline and clinical-trial change events

> Detected changes, newest first, timed by `detected_at`.

- `entity=program` (default): a program added (`insert`), a program changing phase or details (`update`), or a program leaving a company's pipeline (`delete`). Each change names its `program_id`; `GET /v1/programs/{program_id}` returns that program. Retracted changes are hidden unless `include_invalidated=true`.
- `entity=trial`: ClinicalTrials.gov catalyst changes, one row per trial, `kind` and registry update date: a new or removed trial (`trial`), recruitment `status`, `phase`, `start_date`, `primary_completion_date`, `completion_date`, `results_posted`, `enrollment` and `why_stopped`, with `old_value` and `new_value`. Filter with `kind`, `nct_id`, `change_type` and `company_id` (trials linked to the company through its programs or sponsorship). History starts 2026-06-15.

Page with the returned `next_cursor` via `?cursor=`; it stays gap-free while new changes arrive. `since=` bounds the start.



## OpenAPI

````yaml /openapi.json get /v1/changes
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/changes:
    get:
      tags:
        - changes
      summary: List pipeline and clinical-trial change events
      description: >-
        Detected changes, newest first, timed by `detected_at`.


        - `entity=program` (default): a program added (`insert`), a program
        changing phase or details (`update`), or a program leaving a company's
        pipeline (`delete`). Each change names its `program_id`; `GET
        /v1/programs/{program_id}` returns that program. Retracted changes are
        hidden unless `include_invalidated=true`.

        - `entity=trial`: ClinicalTrials.gov catalyst changes, one row per
        trial, `kind` and registry update date: a new or removed trial
        (`trial`), recruitment `status`, `phase`, `start_date`,
        `primary_completion_date`, `completion_date`, `results_posted`,
        `enrollment` and `why_stopped`, with `old_value` and `new_value`. Filter
        with `kind`, `nct_id`, `change_type` and `company_id` (trials linked to
        the company through its programs or sponsorship). History starts
        2026-06-15.


        Page with the returned `next_cursor` via `?cursor=`; it stays gap-free
        while new changes arrive. `since=` bounds the start.
      operationId: list_changes
      parameters:
        - name: entity
          in: query
          required: false
          schema:
            enum:
              - program
              - trial
            type: string
            description: 'Which feed: `program` (default) or `trial`.'
            examples:
              - trial
            default: program
            title: Entity
          description: 'Which feed: `program` (default) or `trial`.'
        - name: company_id
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: integer
              - type: 'null'
            description: Filter to these Pav company ids. Repeatable.
            examples:
              - 412
            title: Company Id
          description: Filter to these Pav company ids. Repeatable.
        - name: change_type
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  enum:
                    - insert
                    - update
                    - delete
                  type: string
              - type: 'null'
            description: 'Filter by change type: `insert`, `update`, `delete`. Repeatable.'
            examples:
              - update
            title: Change Type
          description: 'Filter by change type: `insert`, `update`, `delete`. Repeatable.'
        - name: kind
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  enum:
                    - trial
                    - status
                    - phase
                    - start_date
                    - primary_completion_date
                    - completion_date
                    - results_posted
                    - enrollment
                    - why_stopped
                  type: string
              - type: 'null'
            description: '`entity=trial` only: filter by what changed. Repeatable.'
            examples:
              - status
            title: Kind
          description: '`entity=trial` only: filter by what changed. Repeatable.'
        - name: nct_id
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: '`entity=trial` only: filter to these NCT ids. Repeatable.'
            examples:
              - NCT05366478
            title: Nct Id
          description: '`entity=trial` only: filter to these NCT ids. Repeatable.'
        - name: since
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: Only changes detected at or after this timestamp (ISO 8601).
            examples:
              - '2026-06-01T00:00:00Z'
            title: Since
          description: Only changes detected at or after this timestamp (ISO 8601).
        - name: include_invalidated
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              `entity=program` only: include changes later retracted after a
              correction.
            examples:
              - false
            default: false
            title: Include Invalidated
          description: >-
            `entity=program` only: include changes later retracted after a
            correction.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Opaque cursor from a prior response's `next_cursor`. Preferred
              over `offset`; wins when both are sent.
            title: Cursor
          description: >-
            Opaque cursor from a prior response's `next_cursor`. Preferred over
            `offset`; wins when both are sent.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 5000
            minimum: 1
            description: Maximum rows to return (1-5000).
            examples:
              - 50
            default: 50
            title: Limit
          description: Maximum rows to return (1-5000).
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            maximum: 2000000000
            minimum: 0
            description: >-
              Zero-based row offset. Prefer `cursor`, which wins when both are
              sent.
            examples:
              - 0
            default: 0
            title: Offset
          description: >-
            Zero-based row offset. Prefer `cursor`, which wins when both are
            sent.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeFeedResponse'
        '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:
    ChangeFeedResponse:
      anyOf:
        - $ref: '#/components/schemas/ChangeListResponse'
        - $ref: '#/components/schemas/TrialChangeListResponse'
      title: ChangeFeedResponse
      description: >-
        A page of program changes (`entity=program`) or trial changes
        (`entity=trial`).
    ErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
          description: Error detail. Present only on 4xx/5xx responses.
      required:
        - error
      title: ErrorEnvelope
      type: object
    ChangeListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ChangeEvent'
          type: array
          title: Data
          description: Page of pipeline change events.
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination metadata for this page.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: >-
            Opaque cursor to fetch the next page; pass it back as `?cursor=`.
            Null when this page exhausts the feed. Stable under concurrent
            inserts (unlike `offset`).
          examples:
            - <opaque cursor>
      type: object
      required:
        - data
        - pagination
      title: ChangeListResponse
    TrialChangeListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/TrialChangeEvent'
          type: array
          title: Data
          description: Page of trial change events, newest first.
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination metadata for this page.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: >-
            Opaque cursor to fetch the next page; pass it back as `?cursor=`.
            Null when this page exhausts the feed. Stable under concurrent
            inserts (unlike `offset`).
          examples:
            - <opaque cursor>
      type: object
      required:
        - data
        - pagination
      title: TrialChangeListResponse
    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
    ChangeEvent:
      properties:
        id:
          type: integer
          title: Id
          description: Change-event identifier.
          examples:
            - 90211
        program_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Program Id
          description: >-
            Pav program identifier of the changed program; pass it to `GET
            /v1/programs/{program_id}`. Null only on retracted changes recorded
            before program identifiers were attached.
          examples:
            - 9083
        company_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Company Id
          description: Pav company identifier the change belongs to.
          examples:
            - 412
        short_name:
          type: string
          title: Short Name
          description: Slug of the company that owns the changed program.
          examples:
            - pfizer
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
          description: Company display name.
          examples:
            - Pfizer
        drug:
          type: string
          title: Drug
          description: Drug/asset name of the changed program.
          examples:
            - Danuglipron
        indication:
          anyOf:
            - type: string
            - type: 'null'
          title: Indication
          description: Indication of the changed program.
          examples:
            - Type 2 Diabetes
        territory:
          anyOf:
            - type: string
            - type: 'null'
          title: Territory
          description: Territory of the changed program, when disclosed.
          examples:
            - United States
        change_type:
          type: string
          title: Change Type
          description: >-
            `insert` (program added), `update` (phase or details changed), or
            `delete` (program left the company's pipeline).
          examples:
            - update
        prev_phase:
          anyOf:
            - type: string
            - type: 'null'
          title: Prev Phase
          description: Phase before the change (raw label).
          examples:
            - Phase 1
        new_phase:
          anyOf:
            - type: string
            - type: 'null'
          title: New Phase
          description: Phase after the change (raw label).
          examples:
            - Phase 2
        invalidated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Invalidated At
          description: >-
            When this change was retracted after a correction. Null unless
            `include_invalidated=true` surfaces a retracted change.
          examples:
            - '2026-06-20T04:12:00Z'
        invalidation_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Invalidation Reason
          description: Reason the change was invalidated, if any.
          examples:
            - source correction
        detected_at:
          type: string
          format: date-time
          title: Detected At
          description: When the change was first detected (UTC).
          examples:
            - '2026-06-19T04:12:00Z'
      type: object
      required:
        - id
        - short_name
        - drug
        - change_type
        - detected_at
      title: ChangeEvent
    Pagination:
      properties:
        limit:
          type: integer
          title: Limit
          description: Maximum number of rows returned for this request.
          examples:
            - 100
        offset:
          type: integer
          title: Offset
          description: Zero-based row offset applied before returning results.
          examples:
            - 0
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
          description: >-
            Total matching rows across all pages. Null unless the request set
            `include_total=true` on an endpoint that supports it.
          examples:
            - 590355
      type: object
      required:
        - limit
        - offset
      title: Pagination
    TrialChangeEvent:
      properties:
        id:
          type: integer
          title: Id
          description: Change-event identifier.
          examples:
            - 48213
        entity:
          type: string
          const: trial
          title: Entity
          description: Always `trial` for this feed.
          default: trial
        nct_id:
          type: string
          title: Nct Id
          description: ClinicalTrials.gov identifier of the changed trial.
          examples:
            - NCT05366478
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Trial title, for convenience.
          examples:
            - A Study of Tulisokibart in Ulcerative Colitis
        kind:
          type: string
          enum:
            - trial
            - status
            - phase
            - start_date
            - primary_completion_date
            - completion_date
            - results_posted
            - enrollment
            - why_stopped
          title: Kind
          description: >-
            What changed: `trial` (the trial was registered, or removed from the
            registry), `status` (overall recruitment status), `phase`,
            `start_date`, `primary_completion_date`, `completion_date`,
            `results_posted` (results first posted), `enrollment` (target or
            actual participant count), or `why_stopped`.
          examples:
            - status
        change_type:
          type: string
          enum:
            - insert
            - update
            - delete
          title: Change Type
          description: >-
            `insert` (value first set, or a new trial), `update` (value
            changed), or `delete` (value removed, or the trial left the
            registry).
          examples:
            - update
        old_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Old Value
          description: >-
            Value before the change, as the registry states it. Phases are
            joined with `|`; dates are `YYYY-MM-DD` or `YYYY-MM`.
          examples:
            - RECRUITING
        new_value:
          anyOf:
            - type: string
            - type: 'null'
          title: New Value
          description: Value after the change, in the same form as `old_value`.
          examples:
            - ACTIVE_NOT_RECRUITING
        change_date:
          type: string
          format: date
          title: Change Date
          description: Date the registry published the update.
          examples:
            - '2026-09-24'
        detected_at:
          type: string
          format: date-time
          title: Detected At
          description: >-
            When Pav recorded the change (UTC); the feed is ordered by it.
            History loaded when the feed started carries its `change_date` at
            midnight UTC.
          examples:
            - '2026-09-25T14:31:12Z'
      type: object
      required:
        - id
        - nct_id
        - kind
        - change_type
        - change_date
        - detected_at
      title: TrialChangeEvent
  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

````