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

# Get history snapshot

> Get history snapshot: request contract, authentication, parameters and response behavior for the Oddswire private pilot.

Private local pilot with account-wide included credits. Namespace-scoped IDs; overage off. Successful data pages cost one credit; account/errors/304/aborted or timed-out deliveries are free. No payment or source distribution rights are implied.

`GET /v1/history/snapshot`

## Authentication

`ApiKey`

## Parameters

| Name | Location | Required | Description |
| - | - | - | - |
| `namespace` | query | Yes | Explicit namespace; history IDs are permanent source-local IDs. |
| `books` | query | Yes | One to eight entitled source/region IDs. |
| `native_fixture_id` | query | Yes | One to ten permanent source-local canonical fixture IDs from mappings.native\_fixture\_id. Not the upstream source\_fixture\_id or reviewed group ID. |
| `markets` | query | No | Comma-separated native payout families; default current entitled families. |
| `limit` | query | No | Page size 1..100; coverage remains present on every page. |
| `cursor` | query | No | Opaque whole-query fingerprint; restart explicitly after 409. |
| `as_of` | query | Yes | Inclusive recorded confirmation cutoff. Required for snapshots/lines, cannot be in the future. |
| `If-None-Match` | header | No | Weak semantic ETag; freshness and access are revalidated before 304. |

## Responses

| Status | Meaning |
| - | - |
| 200 | A typed page. Each successful data page costs one included credit, including explicit missing/insufficient states; account introspection is free. missing\[] covers the full query. |
| 304 | Semantically unchanged after authentication and eligibility validation; always zero credits, including at exhausted quota. |
| 400 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 401 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 402 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 403 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 404 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 405 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 409 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 414 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 422 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 429 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 500 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 503 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |
| 504 | Structured problem; see [error handling](https://docs.oddswire.io/errors.md). |

Full request and response schemas: [OpenAPI](https://docs.oddswire.io/openapi.json). [Authentication](https://docs.oddswire.io/authentication.md) · [Prices and coverage](https://docs.oddswire.io/data.md) · [Errors and credits](https://docs.oddswire.io/errors.md).


## OpenAPI

````yaml GET /v1/history/snapshot
openapi: 3.1.2
info:
  description: >-
    Generated from canonical/account/usage DTOs and handler registries. Atomic
    included credits and durable usage, UTC monthly cycles, overage off. Full
    local response write/flush is the observable completion boundary; uncertain
    crash/outage deliveries recover free. Live Clerk login needs provider setup.
    Test-only Stripe billing uses signed durable receipts and reconciled app
    entitlements; real sandbox verification remains open. Dashboard and
    WebSocket are local pilots. Bounded history/as-of/lines and CSV/Parquet
    exports require separate current history/export grants and source-purpose
    reviews. Public launch remains gated. Namespaces are never joined by
    coincident IDs.
  title: Oddswire REST v1 local pilot
  version: 1.0.0
servers:
  - url: http://127.0.0.1:9113
security: []
externalDocs:
  description: WebSocket v1 AsyncAPI contract
  url: http://127.0.0.1:9113/asyncapi.json
paths:
  /v1/history/snapshot:
    get:
      summary: getHistorySnapshot
      description: >-
        Private local pilot with account-wide included credits. Namespace-scoped
        IDs; overage off. Successful data pages cost one credit;
        account/errors/304/aborted or timed-out deliveries are free. No payment
        or source distribution rights are implied.
      operationId: getHistorySnapshot
      parameters:
        - description: Explicit namespace; history IDs are permanent source-local IDs.
          in: query
          name: namespace
          required: true
          schema:
            type: string
        - description: One to eight entitled source/region IDs.
          in: query
          name: books
          required: true
          schema:
            type: string
        - description: >-
            One to ten permanent source-local canonical fixture IDs from
            mappings.native_fixture_id. Not the upstream source_fixture_id or
            reviewed group ID.
          in: query
          name: native_fixture_id
          required: true
          schema:
            type: string
        - description: >-
            Comma-separated native payout families; default current entitled
            families.
          in: query
          name: markets
          required: false
          schema:
            type: string
        - description: Page size 1..100; coverage remains present on every page.
          in: query
          name: limit
          required: false
          schema:
            default: 25
            maximum: 100
            minimum: 1
            type: integer
        - description: Opaque whole-query fingerprint; restart explicitly after 409.
          in: query
          name: cursor
          required: false
          schema:
            type: string
        - description: >-
            Inclusive recorded confirmation cutoff. Required for
            snapshots/lines, cannot be in the future.
          in: query
          name: as_of
          required: true
          schema:
            type: string
        - description: Weak semantic ETag; freshness and access are revalidated before 304.
          in: header
          name: If-None-Match
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoryPage'
          description: >-
            A typed page. Each successful data page costs one included credit,
            including explicit missing/insufficient states; account
            introspection is free. missing[] covers the full query.
          headers:
            X-Oddswire-Credit-Cost:
              $ref: '#/components/headers/X-Oddswire-Credit-Cost'
            X-Oddswire-Credits-Limit:
              $ref: '#/components/headers/X-Oddswire-Credits-Limit'
            X-Oddswire-Credits-Remaining:
              $ref: '#/components/headers/X-Oddswire-Credits-Remaining'
            X-Oddswire-Credits-Reserved:
              $ref: '#/components/headers/X-Oddswire-Credits-Reserved'
            X-Oddswire-Credits-Reset:
              $ref: '#/components/headers/X-Oddswire-Credits-Reset'
            X-Oddswire-Credits-Used:
              $ref: '#/components/headers/X-Oddswire-Credits-Used'
            X-Oddswire-Metering:
              $ref: '#/components/headers/X-Oddswire-Metering'
            X-Oddswire-Overage:
              $ref: '#/components/headers/X-Oddswire-Overage'
            X-Oddswire-Usage-State:
              $ref: '#/components/headers/X-Oddswire-Usage-State'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '304':
          description: >-
            Semantically unchanged after authentication and eligibility
            validation; always zero credits, including at exhausted quota.
          headers:
            X-Oddswire-Credit-Cost:
              $ref: '#/components/headers/X-Oddswire-Credit-Cost'
            X-Oddswire-Credits-Limit:
              $ref: '#/components/headers/X-Oddswire-Credits-Limit'
            X-Oddswire-Credits-Remaining:
              $ref: '#/components/headers/X-Oddswire-Credits-Remaining'
            X-Oddswire-Credits-Reserved:
              $ref: '#/components/headers/X-Oddswire-Credits-Reserved'
            X-Oddswire-Credits-Reset:
              $ref: '#/components/headers/X-Oddswire-Credits-Reset'
            X-Oddswire-Credits-Used:
              $ref: '#/components/headers/X-Oddswire-Credits-Used'
            X-Oddswire-Metering:
              $ref: '#/components/headers/X-Oddswire-Metering'
            X-Oddswire-Overage:
              $ref: '#/components/headers/X-Oddswire-Overage'
            X-Oddswire-Usage-State:
              $ref: '#/components/headers/X-Oddswire-Usage-State'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
        '400':
          $ref: '#/components/responses/Problem'
        '401':
          $ref: '#/components/responses/Problem'
        '402':
          $ref: '#/components/responses/Problem'
        '403':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
        '405':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
        '414':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
        '429':
          $ref: '#/components/responses/Problem'
        '500':
          $ref: '#/components/responses/Problem'
        '503':
          $ref: '#/components/responses/Problem'
        '504':
          $ref: '#/components/responses/Problem'
      security:
        - ApiKey: []
components:
  schemas:
    HistoryPage:
      additionalProperties: false
      properties:
        data:
          items:
            $ref: '#/components/schemas/HistoryRecord'
          type: array
        history:
          $ref: '#/components/schemas/HistoryMetadata'
        meta:
          $ref: '#/components/schemas/Meta'
        missing:
          items:
            $ref: '#/components/schemas/Missing'
          type: array
      required:
        - data
        - missing
        - meta
        - history
      type: object
    HistoryRecord:
      additionalProperties: false
      properties:
        confirmation:
          $ref: '#/components/schemas/HistoryConfirmation'
        cutoff:
          format: date-time
          type: string
        ingest_seq:
          type: string
        kind:
          enum:
            - tick
            - snapshot
            - opening
            - closing
          type: string
        native_fixture_id:
          $ref: '#/components/schemas/ID'
        observation:
          $ref: '#/components/schemas/PriceObservation'
        quote_key:
          type: string
        reason:
          type: string
        source_id:
          $ref: '#/components/schemas/ID'
        status:
          enum:
            - recorded
            - available
            - missing
            - not_final
          type: string
      required:
        - kind
        - source_id
        - native_fixture_id
        - quote_key
        - status
        - reason
      type: object
    HistoryMetadata:
      additionalProperties: false
      properties:
        canonical_sink_verified:
          type: boolean
        capture_high_seq:
          type: string
        closing_policy:
          type: string
        confirmation_policy:
          type: string
        coverage:
          items:
            $ref: '#/components/schemas/HistoryCoverage'
          type: array
        historical_only:
          type: boolean
        history_high_seq:
          type: string
        identity_scope:
          type: string
        namespace:
          type: string
        opening_policy:
          type: string
        query:
          $ref: '#/components/schemas/HistoryQuery'
        timeline:
          type: string
        version:
          type: string
      required:
        - namespace
        - version
        - identity_scope
        - timeline
        - query
        - coverage
        - history_high_seq
        - capture_high_seq
        - confirmation_policy
        - closing_policy
        - opening_policy
        - historical_only
        - canonical_sink_verified
      type: object
    Meta:
      additionalProperties: false
      properties:
        consistency:
          type: string
        count:
          type: integer
        namespace:
          type: string
        next_cursor:
          type: string
        request_id:
          type: string
        sent_ts:
          format: date-time
          type: string
        snapshot_ts:
          format: date-time
          type: string
        version:
          type: string
      required:
        - version
        - request_id
        - sent_ts
        - snapshot_ts
        - next_cursor
        - count
        - consistency
      type: object
    Missing:
      additionalProperties: false
      properties:
        detail:
          type: string
        family:
          $ref: '#/components/schemas/Family'
        fixture_id:
          $ref: '#/components/schemas/ID'
        quote_key:
          type: string
        reason:
          type: string
        source_id:
          $ref: '#/components/schemas/ID'
      required:
        - reason
        - detail
      type: object
    Problem:
      additionalProperties: false
      properties:
        code:
          type: string
        detail:
          type: string
        invalid_params:
          items:
            $ref: '#/components/schemas/InvalidParam'
          type: array
        missing:
          items:
            $ref: '#/components/schemas/Missing'
          type: array
        request_id:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - request_id
        - invalid_params
        - missing
      type: object
    HistoryConfirmation:
      additionalProperties: false
      properties:
        capture_id:
          type: string
        capture_seq:
          type: string
        confirmed_ts:
          format: date-time
          type: string
        recorded_fixture_status:
          type: string
        recorded_scheduled_start:
          format: date-time
          type: string
      required:
        - capture_id
        - capture_seq
        - confirmed_ts
        - recorded_scheduled_start
        - recorded_fixture_status
      type: object
    ID:
      maximum: 9007199254740991
      minimum: 1
      type: integer
    PriceObservation:
      additionalProperties: false
      properties:
        event_id:
          format: uuid
          type: string
        key:
          $ref: '#/components/schemas/PriceKey'
        raw_payload_id:
          format: uuid
          type: string
        seen_ts:
          format: date-time
          type: string
        source_sequence:
          type: string
        source_ts:
          format: date-time
          type: string
        value:
          $ref: '#/components/schemas/PriceValue'
      required:
        - event_id
        - raw_payload_id
        - key
        - value
        - seen_ts
      type: object
    HistoryCoverage:
      additionalProperties: false
      properties:
        binding:
          $ref: '#/components/schemas/HistoryBinding'
        first_confirmation:
          format: date-time
          type: string
        first_tick:
          format: date-time
          type: string
        gaps:
          items:
            type: string
          type: array
        last_confirmation:
          format: date-time
          type: string
        last_tick:
          format: date-time
          type: string
        max_confirmation_gap_seconds:
          type: number
        recorded_confirmations:
          type: integer
        retained_ticks:
          type: integer
        source_pending_captures:
          type: integer
        source_quarantined_captures:
          type: integer
        status:
          type: string
      required:
        - binding
        - status
        - retained_ticks
        - recorded_confirmations
        - source_pending_captures
        - source_quarantined_captures
        - gaps
      type: object
    HistoryQuery:
      additionalProperties: false
      properties:
        as_of:
          format: date-time
          type: string
        books:
          items:
            $ref: '#/components/schemas/ID'
          type: array
        families:
          items:
            $ref: '#/components/schemas/Family'
          type: array
        from:
          format: date-time
          type: string
        kind:
          type: string
        native_fixture_ids:
          items:
            $ref: '#/components/schemas/ID'
          type: array
        scheduled_start:
          format: date-time
          type: string
        until:
          format: date-time
          type: string
      required:
        - kind
        - books
        - native_fixture_ids
        - families
      type: object
    Family:
      enum:
        - 1x2
        - total
        - asian_handicap
      type: string
    InvalidParam:
      additionalProperties: false
      properties:
        name:
          type: string
        reason:
          type: string
      required:
        - name
        - reason
      type: object
    PriceKey:
      additionalProperties: false
      properties:
        depth:
          maximum: 3
          type: integer
        fixture_id:
          $ref: '#/components/schemas/ID'
        market_id:
          $ref: '#/components/schemas/ID'
        outcome_id:
          $ref: '#/components/schemas/ID'
        side:
          $ref: '#/components/schemas/Side'
        source_fixture_id:
          minLength: 1
          type: string
        source_id:
          $ref: '#/components/schemas/ID'
        source_market_id:
          minLength: 1
          type: string
        source_outcome_id:
          minLength: 1
          type: string
      required:
        - source_id
        - fixture_id
        - market_id
        - outcome_id
        - source_fixture_id
        - source_market_id
        - source_outcome_id
        - side
        - depth
      type: object
    PriceValue:
      additionalProperties: false
      properties:
        available_size:
          $ref: '#/components/schemas/Decimal'
        commission_rate:
          $ref: '#/components/schemas/Decimal'
        currency:
          pattern: ^[A-Z]{3}$
          type: string
        decimal_odds:
          $ref: '#/components/schemas/Decimal'
        fee_rate:
          $ref: '#/components/schemas/Decimal'
        main_line:
          type: boolean
        native_unit:
          $ref: '#/components/schemas/NativeUnit'
        native_value:
          $ref: '#/components/schemas/Decimal'
        size_unit:
          enum:
            - currency
            - contracts
          type: string
        state:
          $ref: '#/components/schemas/PriceState'
      required:
        - state
        - native_unit
      type: object
    HistoryBinding:
      additionalProperties: false
      properties:
        freshness_limit_seconds:
          type: integer
        known:
          type: boolean
        native_fixture_id:
          $ref: '#/components/schemas/ID'
        source_id:
          $ref: '#/components/schemas/ID'
        source_region:
          type: string
        sport_id:
          $ref: '#/components/schemas/ID'
      required:
        - source_id
        - source_region
        - native_fixture_id
        - known
        - freshness_limit_seconds
      type: object
    Side:
      enum:
        - quote
        - back
        - lay
        - bid
        - ask
      type: string
    Decimal:
      pattern: ^(0|[1-9][0-9]{0,15})\.[0-9]{8}$
      type: string
    NativeUnit:
      enum:
        - decimal_odds
        - probability
      type: string
    PriceState:
      enum:
        - active
        - suspended
        - unavailable
      type: string
  headers:
    X-Oddswire-Credit-Cost:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Oddswire-Credits-Limit:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Oddswire-Credits-Remaining:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Oddswire-Credits-Reserved:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Oddswire-Credits-Reset:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Oddswire-Credits-Used:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Oddswire-Metering:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Oddswire-Overage:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Oddswire-Usage-State:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
    X-Request-ID:
      description: >-
        Account-scoped admission snapshot where authenticated: remaining
        excludes holds; used counts settled calls. Cost 1 reserves one credit;
        actual charge settles only after complete local write/flush. Inspect
        free account/usage by request ID for final state. UTC reset is RFC3339;
        overage is off. Unknown credentials disclose no account counters.
      schema:
        type: string
  responses:
    Problem:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      description: >-
        Structured actionable problem; errors consume zero credits. Quota
        exhaustion/unconfigured returns 402 with counters/reset headers and free
        usage guidance. 429 Retry-After is separate abuse control. No database
        details or credentials.
      headers:
        X-Oddswire-Credit-Cost:
          $ref: '#/components/headers/X-Oddswire-Credit-Cost'
        X-Oddswire-Credits-Limit:
          $ref: '#/components/headers/X-Oddswire-Credits-Limit'
        X-Oddswire-Credits-Remaining:
          $ref: '#/components/headers/X-Oddswire-Credits-Remaining'
        X-Oddswire-Credits-Reserved:
          $ref: '#/components/headers/X-Oddswire-Credits-Reserved'
        X-Oddswire-Credits-Reset:
          $ref: '#/components/headers/X-Oddswire-Credits-Reset'
        X-Oddswire-Credits-Used:
          $ref: '#/components/headers/X-Oddswire-Credits-Used'
        X-Oddswire-Metering:
          $ref: '#/components/headers/X-Oddswire-Metering'
        X-Oddswire-Overage:
          $ref: '#/components/headers/X-Oddswire-Overage'
        X-Oddswire-Usage-State:
          $ref: '#/components/headers/X-Oddswire-Usage-State'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
  securitySchemes:
    ApiKey:
      in: header
      name: X-API-Key
      type: apiKey

````

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