Gloom Bulk API

openapi: 3.2.0
info:
  title: Gloom Datasets Bulk API
  version: '2026-11-10'
  description: 'Gloom Datasets API. Authenticate with a `gds_` key. Prices and limits: https://gloom.sh/datasets/pricing. Changes: https://gloom.sh/datasets/docs/changelog.


    Every response is `{data, meta}` and every error `{error: {type, code, message, param, requestId, docUrl}}`. Dataset routes sit directly under /v1; the catalog, account and reference routes under /v1/datasets. Company routes take symbols=, listings in any notation (AAPL, BRK-B, AIR.PA, VOD:XLON), as many as the route''s x-symbols.max: each item names its canonical listing, meta.symbols reports every input, and a listing the dataset does not know is free. Paths renamed in 2026-10-23 answer 308 to their new path until 2027-01-23 (x-redirects). Gloom Datasets keys and Gloom Pro keys are different keys for different APIs: each is refused by the other''s routes. Every route is also a tool of the MCP server at https://api.gloom.sh/v1/datasets/mcp (Streamable HTTP; x-mcp), with the same key and price. No key? Pay each call with x402: a call with no key answers 402 with its price in the PAYMENT-REQUIRED header; pay it in USDC on Base ($0.03 a credit) and send the same request with PAYMENT-SIGNATURE (x-x402, https://gloom.sh/datasets/docs/x402).'
  x-mcp:
    url: https://api.gloom.sh/v1/datasets/mcp
    transport: streamable-http
    docs: https://gloom.sh/datasets/docs/mcp
  termsOfService: https://gloom.sh/datasets/terms
  contact:
    name: Gloom Datasets
    url: https://gloom.sh/datasets/docs
    email: hello@gloom.sh
  x-guidance: 'Gloom Datasets sells financial and alternative datasets (SEC filings, fundamentals, options, macro, hiring, GPU prices and more), one JSON route per dataset under /v1. Every route is paid per call with x402, in USDC on Base, with no account: a request with no payment answers 402 and its PAYMENT-REQUIRED header holds the price; the same request with a signed PAYMENT-SIGNATURE header is answered and then settled. A credit costs $0.03; each route''s price is in its x-payment-info, and routes that take symbols= (AAPL,MSFT) charge each listing the dataset holds. GET /v1/datasets lists the datasets and GET /v1/datasets/{id}/sample answers a dataset''s free sample. Parameters, limits and response schemas are described per route. Docs: https://gloom.sh/datasets/docs/x402.'
servers:
- url: https://api.gloom.sh
security:
- bearer: []
- apiKey: []
tags:
- name: Bulk
  description: Daily snapshot files, exports over many listings, and webhooks. Each costs the credits of the same rows read call by call.
paths:
  /v1/datasets/{id}/snapshots:
    get:
      operationId: snapshots.list
      tags:
      - Bulk
      summary: A dataset's daily snapshots, with prices
      description: The days kept, newest first, each with its rows and what it costs. A snapshot holds the whole dataset as its route lists it, read once the UTC day is over. Kept 7 days. Free, no key. https://gloom.sh/datasets/docs/bulk
      security: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          enum:
          - app-attention
          - awards
          - catalysts
          - central-bank-rates
          - congress
          - cot
          - cpi
          - credit-documents
          - depositary-receipts
          - earnings
          - energy-inventories
          - gpu
          - hiring-jobs
          - hiring-momentum
          - ipo
          - mna
          - perps
          - transcripts
      - $ref: '#/components/parameters/GloomVersion'
      x-credit-cost: 0
      responses:
        '200':
          description: Snapshots kept.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Snapshot'
                  meta:
                    $ref: '#/components/schemas/Meta'
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Gloom-Version:
              $ref: '#/components/headers/GloomVersion'
            X-Credits-Cost:
              $ref: '#/components/headers/CreditsCost'
            X-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
            X-Plan:
              $ref: '#/components/headers/Plan'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            ETag:
              $ref: '#/components/headers/ETag'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
components:
  parameters:
    GloomVersion:
      name: Gloom-Version
      in: header
      required: false
      description: Optional. Every route answers in the latest version whatever this names; a value that names no published version is refused with version_invalid.
      schema:
        type: string
        enum:
        - '2026-11-10'
        - '2026-11-09'
        - '2026-11-08'
        - '2026-11-07'
        - '2026-11-06'
        - '2026-11-05'
        - '2026-11-04'
        - '2026-10-31'
        - '2026-10-30'
        - '2026-10-29'
        - '2026-10-27'
        - '2026-10-26'
        - '2026-10-25'
        - '2026-10-24'
        - '2026-10-23'
        - '2026-10-21'
  headers:
    Allow:
      description: 'The methods this path takes, on a 405: a wrong method is answered for the path, so every operation below lists it.'
      schema:
        type: string
        examples:
        - GET
    RateLimitReset:
      description: Seconds until the current minute ends.
      schema:
        type: integer
        minimum: 1
    CreditsRemaining:
      description: Credits remaining in the account's current period.
      schema:
        type: integer
        minimum: 0
    RequestId:
      description: This request's id. Quote it to support.
      schema:
        type: string
    CreditsCost:
      description: 'Credits charged for this request. An error is never charged: a call that fails after its charge, 4xx or 5xx, is refunded. A 304 is free.'
      schema:
        type: integer
        minimum: 0
    ETag:
      description: A validator for this body. Send it back as If-None-Match to get a free 304 when nothing changed.
      schema:
        type: string
    Plan:
      schema:
        type: string
        enum:
        - free
        - reference_personal
        - reference_company
        - filings_personal
        - filings_company
        - news_personal
        - news_company
        - everything_personal
        - everything_company
        - basic
        - desk
        - enterprise
    GloomVersion:
      description: 'The contract version that answered: always the latest.'
      schema:
        type: string
        enum:
        - '2026-11-10'
        - '2026-11-09'
        - '2026-11-08'
        - '2026-11-07'
        - '2026-11-06'
        - '2026-11-05'
        - '2026-11-04'
        - '2026-10-31'
        - '2026-10-30'
        - '2026-10-29'
        - '2026-10-27'
        - '2026-10-26'
        - '2026-10-25'
        - '2026-10-24'
        - '2026-10-23'
        - '2026-10-21'
    RateLimitRemaining:
      description: Credits left in the key's sliding minute.
      schema:
        type: integer
        minimum: 0
    RateLimitLimit:
      description: Credits the key may spend a minute.
      schema:
        type: integer
        minimum: 0
  schemas:
    Snapshot:
      type: object
      required:
      - dataset
      - date
      - rows
      - credits
      - files
      - path
      properties:
        dataset:
          type: string
        date:
          type: string
          format: date
          description: The UTC day the snapshot holds the dataset as of its end.
        rows:
          type: integer
          minimum: 0
        credits:
          type: integer
          minimum: 0
          description: 'What it costs: the credits of reading the same rows through the dataset''s routes, call by call.'
        files:
          type: array
          items:
            $ref: '#/components/schemas/SnapshotFile'
        path:
          type: string
          description: Where its files are asked for.
    SnapshotFile:
      type: object
      required:
      - format
      - bytes
      - sha256
      properties:
        format:
          type: string
          enum:
          - ndjson
          - parquet
        bytes:
          type: integer
          minimum: 0
        sha256:
          type: string
          description: SHA-256 of the file as downloaded, in hex.
    Meta:
      type: object
      required:
      - dataset
      - requestId
      - asOf
      - dataThrough
      - historyStart
      - updatedAt
      - page
      - next
      - coverage
      - source
      - notices
      - symbols
      properties:
        dataset:
          type:
          - string
          - 'null'
          enum:
          - gpu
          - hiring-jobs
          - hiring-momentum
          - app-attention
          - awards
          - kpis-guidance
          - credit-documents
          - power
          - perps
          - catalysts
          - supply-chain
          - exposure
          - transcripts
          - exec-pay
          - risk-factors
          - events
          - document-search
          - news
          - social-mentions
          - cpi
          - energy-inventories
          - cot
          - short-volume
          - short-interest
          - sec
          - congress
          - macro
          - central-bank-rates
          - cds
          - debt-maturities
          - revenue-breakdown
          - depositary-receipts
          - bond-trades
          - market-data
          - futures
          - rate-path
          - options
          - earnings
          - ipo
          - mna
          - equity-screener
          - crypto
          - session-tape
          - analyst-estimates
          - null
        requestId:
          type: string
          description: Quote it to support.
        asOf:
          type:
          - string
          - 'null'
          description: The point in time you asked for with asOf, or null for the latest.
        dataThrough:
          type:
          - string
          - 'null'
          description: The newest date or time the data covers.
        historyStart:
          type:
          - string
          - 'null'
          description: Earliest date the dataset has history for, when known; otherwise null.
        updatedAt:
          type:
          - string
          - 'null'
          description: When the data last changed, when known.
        page:
          oneOf:
          - type: 'null'
          - type: object
            required:
            - limit
            - hasMore
            - nextCursor
            - total
            properties:
              limit:
                type: integer
                minimum: 1
              hasMore:
                type: boolean
              nextCursor:
                type:
                - string
                - 'null'
              total:
                type:
                - integer
                - 'null'
                minimum: 0
                description: Rows that match the query on every page, where the route counts them; null where it does not.
          description: Paging of a list; null for a single record.
        next:
          type:
          - string
          - 'null'
          description: The next page as a ready URL, or null.
        coverage:
          description: Service-established coverage; null when unavailable.
        source:
          type: array
          items:
            type: object
            required:
            - id
            - attribution
            - licence
            properties:
              id:
                type: string
              attribution:
                type: string
              licence:
                type: string
        delayed:
          type: boolean
          const: true
          description: Present, and true, only on market prices that follow delayed-data access.
        notices:
          type: array
          items:
            $ref: '#/components/schemas/Notice'
          description: 'Caveats that change how to read the data: disclaimers, gaps, illustrative samples.'
        sampledAt:
          type:
          - string
          - 'null'
          description: 'Only on sample routes: when the sample was read from the dataset. Null for the built-in example, served until the first daily read succeeds.'
        symbols:
          oneOf:
          - type: 'null'
          - type: array
            items:
              $ref: '#/components/schemas/SymbolResult'
          description: 'Each listing a symbols= call named, in the order sent: as sent, its canonical listing and whether it was read. Only ok listings are charged. Null when the call named none.'
        cursor:
          type:
          - string
          - 'null'
          description: 'Only on a change feed (/v1/catalysts/changes, /v1/insider-trades/changes): the cursor to send as cursor on the next poll, with the same since and symbols. It is there caught up too, when meta.next is null. One cursor serves all the symbols of the call: on /v1/catalysts/changes it is the earliest of the listings'', each of which is also in meta.symbols.'
        checkedAt:
          type:
          - string
          - 'null'
          description: 'Only on a change feed (/v1/catalysts/changes, /v1/insider-trades/changes): when its collector last finished reading its sources, rows or none, so a quiet feed reads apart from a stalled one; on /v1/catalysts/changes the newest of its sources'' last reads. It is in no ETag, and the X-Checked-At header carries it on a 304 too. Null when not recorded.'
        pointInTime:
          type: object
          required:
          - cutoff
          - basis
          - versions
          properties:
            cutoff:
              type: string
              format: date-time
              description: 'The last moment the read counts, in UTC: a date''s is the end of that day.'
            basis:
              type: string
              enum:
              - observedAt
              - publishedAt
              description: 'observedAt: the rows Gloom had stored by the cutoff. publishedAt: the route does not record when Gloom stored each row, so the rows are those their source had published by then.'
            versions:
              type: string
              enum:
              - kept
              - unchanged
              - latest
              description: 'kept: each row has the values it had then. unchanged: so does each row, and a row changed since is left out. latest: each row has its values now, which may hold a revision made after the cutoff.'
          description: 'Only on a call that sent asOf: what the answer is. Unless basis is observedAt and versions kept, a point_in_time notice says what the route cannot give.'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - code
          - message
          - param
          - requestId
          - docUrl
          properties:
            type:
              type: string
              enum:
              - invalid_request
              - authentication
              - plan
              - permission
              - not_found
              - rate_limit
              - api_error
              description: Branch on the type first.
            code:
              type: string
              enum:
              - parameter_unknown
              - parameter_missing
              - parameter_invalid
              - parameter_repeated
              - cursor_invalid
              - body_invalid
              - version_invalid
              - missing_key
              - invalid_key
              - wrong_key
              - plan_required
              - dataset_not_included
              - key_disabled
              - not_found
              - method_not_allowed
              - idempotency_conflict
              - rate_limited
              - credits_exhausted
              - unavailable
              - payment_required
              - payment_invalid
              - payment_failed
              - payment_unconfirmed
              description: The specific reason. Messages may change; codes do not.
            message:
              type: string
            param:
              type:
              - string
              - 'null'
              description: The parameter or header the error is about.
            requestId:
              type: string
            docUrl:
              type: string
              format: uri
    Notice:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
        message:
          type: string
    SymbolResult:
      type: object
      required:
      - input
      - symbol
      - status
      properties:
        input:
          type: string
          description: As sent.
        symbol:
          type:
          - string
          - 'null'
          description: 'The canonical listing: the bare symbol on a US venue (BRK.B), else SYMBOL:MIC (AIR:XPAR). Null when the notation names no listing.'
        status:
          type: string
          enum:
          - ok
          - empty
          - not_found
          - unavailable
          - partial
          description: 'ok: read and charged. empty: a listing Gloom knows that the dataset holds nothing for here, or does not cover (an outside_coverage notice names those); free. not_found: no listing Gloom knows; free. unavailable: it could not be read now; free, retry later. partial: read in part, free, send it again.'
        cursor:
          type:
          - string
          - 'null'
          description: 'Only on a route that pages by its own cursor: where this listing reads on. Send it as cursor with symbols= naming this listing alone. On a change feed it is there caught up too. Null when the listing has no more, or was not read.'
  responses:
    Error405:
      description: 'invalid_request: method_not_allowed.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Gloom-Version:
          $ref: '#/components/headers/GloomVersion'
        X-Credits-Cost:
          $ref: '#/components/headers/CreditsCost'
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
        X-Plan:
          $ref: '#/components/headers/Plan'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Allow:
          $ref: '#/components/headers/Allow'
    Error404:
      description: 'not_found: not_found.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Gloom-Version:
          $ref: '#/components/headers/GloomVersion'
        X-Credits-Cost:
          $ref: '#/components/headers/CreditsCost'
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
        X-Plan:
          $ref: '#/components/headers/Plan'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: A Gloom Datasets key, starting gds_. Gloom Pro and News API keys are refused with wrong_key.
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
externalDocs:
  description: Documentation
  url: https://gloom.sh/datasets/docs
x-x402:
  x402Version: 2
  scheme: exact
  asset: USDC
  network: eip155:8453
  networkName: Base
  centsPerCredit: 3
  paymentRequiredHeader: PAYMENT-REQUIRED
  paymentHeader: PAYMENT-SIGNATURE
  receiptHeader: PAYMENT-RESPONSE
  description: 'A call with no key answers 402 payment_required: PAYMENT-REQUIRED holds the x402 payment requirements (base64 JSON) for the call''s credits at $0.03 each. Sign that exact USDC payment and send the same request with it in PAYMENT-SIGNATURE. It settles only when the call answers; PAYMENT-RESPONSE carries the receipt. A request with a key never pays with x402.'
  docs: https://gloom.sh/datasets/docs/x402
x-plans:
  none:
    credits: 0
    perMinute: 0
    maxKeys: 0
    monthlyPriceUsd: null
    yearlyPriceUsd: null
    scope: null
    use: null
    offered: false
  free:
    credits: 100
    perMinute: 300
    maxKeys: 1
    monthlyPriceUsd: 0
    yearlyPriceUsd: 0
    scope: everything
    use: null
    offered: true
  reference_personal:
    credits: 150000
    perMinute: 300
    maxKeys: 5
    monthlyPriceUsd: 49
    yearlyPriceUsd: 490
    scope: reference
    use: personal
    offered: true
  reference_company:
    credits: 1000000
    perMinute: 1200
    maxKeys: 20
    monthlyPriceUsd: 149
    yearlyPriceUsd: 1490
    scope: reference
    use: company
    offered: true
  filings_personal:
    credits: 150000
    perMinute: 300
    maxKeys: 5
    monthlyPriceUsd: 99
    yearlyPriceUsd: 990
    scope: filings
    use: personal
    offered: true
  filings_company:
    credits: 1000000
    perMinute: 1200
    maxKeys: 20
    monthlyPriceUsd: 299
    yearlyPriceUsd: 2990
    scope: filings
    use: company
    offered: true
  news_personal:
    credits: 150000
    perMinute: 300
    maxKeys: 5
    monthlyPriceUsd: 199
    yearlyPriceUsd: 1990
    scope: news
    use: personal
    offered: true
  news_company:
    credits: 1000000
    perMinute: 1200
    maxKeys: 20
    monthlyPriceUsd: 799
    yearlyPriceUsd: 7990
    scope: news
    use: company
    offered: true
  everything_personal:
    credits: 150000
    perMinute: 300
    maxKeys: 5
    monthlyPriceUsd: 299
    yearlyPriceUsd: 2990
    scope: everything
    use: personal
    offered: true
  everything_company:
    credits: 1000000
    perMinute: 1200
    maxKeys: 20
    monthlyPriceUsd: 1199
    yearlyPriceUsd: 11990
    scope: everything
    use: company
    offered: true
  basic:
    credits: 150000
    perMinute: 300
    maxKeys: 5
    monthlyPriceUsd: 200
    yearlyPriceUsd: 2000
    scope: everything
    use: company
    offered: false
  desk:
    credits: 1000000
    perMinute: 1200
    maxKeys: 20
    monthlyPriceUsd: 800
    yearlyPriceUsd: 8000
    scope: everything
    use: company
    offered: false
  enterprise:
    credits: null
    perMinute: null
    maxKeys: null
    monthlyPriceUsd: null
    yearlyPriceUsd: null
    scope: everything
    use: null
    offered: false
x-enterprise-default-limits:
  perMinute: 6000
  maxKeys: 100
x-credit-call-types:
  lookup: 1
  history: 2
  search: 2
  evidence: 5
  bulk: 25
  change: 1
x-bulk-plans:
- reference_personal
- reference_company
- filings_personal
- filings_company
- news_personal
- news_company
- everything_personal
- everything_company
- basic
- desk
- enterprise