MetricDuck Ir Documents API

The ir-documents API from MetricDuck — 1 operation(s) for ir-documents.

GitHub OpenAPI

Operations 1

GET /api/v1/ir-documents Retrieve IR earnings-presentation-deck text (forward guidance / KPIs not in SEC… #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/metricduck-com:metricduck-com-ir-documents-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

metricduck-com-ir-documents-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Metric Duck Ir Documents API
  description: 'SEC filing data API: equity fundamentals updated daily from SEC EDGAR'
  version: 2.0.0
tags:
- name: ir-documents
paths:
  /api/v1/ir-documents:
    get:
      tags:
      - ir-documents
      summary: Retrieve IR earnings-presentation-deck text (forward guidance / KPIs not in SEC…
      description: Serve the IR earnings PRESENTATION DECK (slide-deck) text that lives ONLY in the company's investor-relations deck — forward guidance, operational KPIs, segment outlook — and is NOT in the SEC 8-K/10-Q release text or XBRL. Resolve by ticker or cik; narrow with fiscal_year/fiscal_period; pass `query` to return only the slide pages whose text matches (page-cited).
      operationId: get_ir_documents_api_v1_ir_documents_get
      security:
      - HTTPBearer: []
      - APIKeyHeader: []
      parameters:
      - name: ticker
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 10
          - type: 'null'
          description: Company ticker (e.g., OXY). Either ticker or cik required.
          title: Ticker
        description: Company ticker (e.g., OXY). Either ticker or cik required.
      - name: cik
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^\d{10}$
          - type: 'null'
          description: 10-digit CIK as an alternative to ticker.
          title: Cik
        description: 10-digit CIK as an alternative to ticker.
      - name: fiscal_year
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 2100
            minimum: 2000
          - type: 'null'
          description: Fiscal year of the deck (e.g., 2024).
          title: Fiscal Year
        description: Fiscal year of the deck (e.g., 2024).
      - name: fiscal_period
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 8
          - type: 'null'
          description: 'Fiscal period: ''Q3'' (with fiscal_year) or combined ''2024Q3''. Optional.'
          title: Fiscal Period
        description: 'Fiscal period: ''Q3'' (with fiscal_year) or combined ''2024Q3''. Optional.'
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 2
            maxLength: 200
          - type: 'null'
          description: Keyword filter over slide text — returns only matching pages (whole-word AND, case-insensitive).
          title: Query
        description: Keyword filter over slide text — returns only matching pages (whole-word AND, case-insensitive).
      - name: coverage_only
        in: query
        required: false
        schema:
          type: boolean
          description: Return only the deck COUNT (total_decks), skipping the slide-text read. For a 'has decks?' coverage check — scans the small ir_documents catalog (~35 MB) instead of the ir_document_text corpus. Used by the web factsheet's coverage line.
          default: false
          title: Coverage Only
        description: Return only the deck COUNT (total_decks), skipping the slide-text read. For a 'has decks?' coverage check — scans the small ir_documents catalog (~35 MB) instead of the ir_document_text corpus. Used by the web factsheet's coverage line.
      - name: list_only
        in: query
        required: false
        schema:
          type: boolean
          description: Return the metadata-only deck INDEX (title/date/url/gcs_uri per deck, NO slide text) for a browsable archive — up to 500 decks + the true total. Scans the ir_documents catalog only (~35 MB), not the text corpus. Mutually exclusive with coverage_only and query.
          default: false
          title: List Only
        description: Return the metadata-only deck INDEX (title/date/url/gcs_uri per deck, NO slide text) for a browsable archive — up to 500 decks + the true total. Scans the ir_documents catalog only (~35 MB), not the text corpus. Mutually exclusive with coverage_only and query.
      - name: api_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IrDocumentsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    IrDocumentsResponse:
      properties:
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
        cik:
          type: string
          title: Cik
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
        query:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
        decks:
          items:
            $ref: '#/components/schemas/IrDeck'
          type: array
          title: Decks
        total_decks:
          type: integer
          title: Total Decks
          default: 0
        source_access:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Access
          description: Honest reachability hint for the issuer's IR SITE (from the resolver's ir_reachability) so an agent doesn't thrash fetching a dead/bot-walled source — e.g. 'bot_walled' (prefer the mirrored copy / extracted text) or 'live'.
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
          description: Coverage note when a catalog deck exists but its text is not yet extracted, when no decks matched, or when the response's page budget left decks out (how many, and how to reach them).
      type: object
      required:
      - cik
      title: IrDocumentsResponse
    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
    IrDeckPage:
      properties:
        page:
          type: integer
          title: Page
          description: 1-based page number within the deck
        text:
          type: string
          title: Text
          description: Extracted slide text (may be truncated)
        truncated:
          type: boolean
          title: Truncated
          description: True when text was capped at the per-page char limit
          default: false
      type: object
      required:
      - page
      - text
      title: IrDeckPage
      description: A single slide/page of extracted deck text.
    IrDeck:
      properties:
        doc_id:
          type: string
          title: Doc Id
          description: Stable deterministic item identity ('{cik10}:u:{sha1(url)}'). Dedup-safe across URL variants; the join/reference key. NOT an event key.
        doc_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Doc Kind
          description: Item type — 'presentation' or 'guidance' (the served kinds). Pipeline-classified; the surface gate.
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
        cik:
          type: string
          title: Cik
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Catalog title (e.g., 'Presentation') when known
        doc_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Doc Date
          description: Fiscal-period ANCHOR date (YYYY-MM-DD) — a synthetic period-END date, NOT the real publish/upload date, and ~24% NULL. Display via fiscal_year/fiscal_period; never render as 'Published {date}' or plot it on a real-time axis (the real event datetime lives on /companies/{ticker}/events occurred_at).
        fiscal_year:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fiscal Year
          description: Best-effort fiscal year (int) parsed from the deck; may be null.
        fiscal_period:
          anyOf:
          - type: string
          - type: 'null'
          title: Fiscal Period
          description: Best-effort BARE fiscal quarter ('Q1'..'Q4' or 'FY'); pair with fiscal_year. Filename/feed-parsed DISCOVERY metadata — may be null; NOT an event key (do not group events on it server-side).
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: RUNG 1 — original IR-hosted source URL (freshest/complete; provenance). Fetch + read this yourself if you can.
        gcs_uri:
          anyOf:
          - type: string
          - type: 'null'
          title: Gcs Uri
          description: RUNG 2 — stable MetricDuck-hosted copy (gs:// URI). Present when we mirrored the deck; fetch THIS if the original url is unreachable / bot-walled / link-rotted — it's the identical bytes, immune to those.
        mirrored:
          type: boolean
          title: Mirrored
          description: True when a stable mirrored copy (gcs_uri) exists — i.e. MetricDuck successfully fetched the deck, so an agent-fetchable path is guaranteed.
          default: false
        total_pages:
          type: integer
          title: Total Pages
          description: Total extracted pages in this deck
          default: 0
        pages:
          items:
            $ref: '#/components/schemas/IrDeckPage'
          type: array
          title: Pages
          description: 'RUNG 3 — MetricDuck-extracted slide text (most reliable: pre-parsed, no fetch/parse needed, immune to bot-walls). When `query` given: only matching pages; else a bounded prefix. Empty when text isn''t extracted yet (use rung 1/2).'
        pages_matched:
          type: integer
          title: Pages Matched
          description: Count of pages matching the query (0 when no query)
          default: 0
        pages_truncated:
          type: boolean
          title: Pages Truncated
          description: True when more pages exist than were returned (raise/refine the query, or read the deck via url/gcs_uri).
          default: false
      type: object
      required:
      - doc_id
      - cik
      title: IrDeck
      description: 'One served IR document (presentation deck or guidance doc) and (optionally) its

        matching slide text. `doc_kind` types the item; `doc_id` is its stable identity.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key