openapi: 3.0.3
info:
  title: KV FastData API - History by Global Key
  version: 3.0.3
  description: Fetch the historical values for a selected key across accounts and predecessors.
paths:
  /v0/history:
    post:
      description: Fetch the historical values for a selected key across accounts and predecessors.
      operationId: history_by_key
      requestBody:
        content:
          application/json:
            example:
              asc: true
              include_metadata: false
              key: graph/follow/sleet.near
              limit: 50
            schema:
              $ref: "#/components/schemas/ByKeyRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                entries:
                  - action_index: 0
                    block_height: 183302718
                    block_timestamp: 1769731630602682600
                    current_account_id: social.near
                    key: graph/follow/sleet.near
                    predecessor_id: james.near
                    receipt_id: gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk
                    signer_id: james.near
                    tx_hash: FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3
                    value: ""
                page_token: opaque-next-page-token
              schema:
                $ref: "#/components/schemas/ListResponse"
          description: Historical rows for the selected key
        "400":
          content:
            application/json:
              example:
                error: invalid page token
              schema:
                $ref: "#/components/schemas/ApiError"
          description: Invalid key filter or page token
        "500":
          content:
            application/json:
              example:
                error: internal server error
              schema:
                $ref: "#/components/schemas/ApiError"
          description: Scylla query failure
      summary: Fetch historical rows by exact key across all indexed contracts
      tags:
        - history
servers:
  - description: Mainnet
    url: https://kv.main.fastnear.com
  - description: Testnet
    url: https://kv.test.fastnear.com
components:
  schemas:
    ApiError:
      additionalProperties: false
      properties:
        error:
          type: string
      required:
        - error
      type: object
    ByKeyRequest:
      additionalProperties: false
      properties:
        asc:
          default: false
          description: Sort ascending for history results. Defaults to newest-first.
          type: boolean
        include_metadata:
          default: false
          description: Include receipt and signer metadata in each entry.
          type: boolean
        key:
          description: Exact key name to match across all accounts and predecessors.
          type: string
        limit:
          description: Maximum number of entries to return in one page (1–200, default 50).
          format: int32
          maximum: 200
          minimum: 1
          nullable: true
          type: integer
        page_token:
          description: Opaque pagination cursor from a previous response for the same endpoint and filter set.
          nullable: true
          type: string
      required:
        - key
      type: object
    KvEntry:
      additionalProperties: false
      properties:
        action_index:
          format: uint32
          minimum: 0
          nullable: true
          type: integer
        block_height:
          format: uint64
          minimum: 0
          type: integer
        block_timestamp:
          format: uint64
          minimum: 0
          type: integer
        current_account_id:
          type: string
        key:
          type: string
        predecessor_id:
          type: string
        receipt_id:
          nullable: true
          type: string
        signer_id:
          nullable: true
          type: string
        tx_hash:
          nullable: true
          type: string
        value:
          description: Raw JSON value as stored in FastData.
      required:
        - predecessor_id
        - current_account_id
        - block_height
        - block_timestamp
        - key
        - value
      type: object
    ListResponse:
      additionalProperties: false
      properties:
        entries:
          items:
            $ref: "#/components/schemas/KvEntry"
          type: array
        page_token:
          description: Opaque pagination cursor for the next page. Absent when there are no more results.
          nullable: true
          type: string
      required:
        - entries
      type: object