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

# Get transaction history

> Retrieve the full version history of a transaction, following the `previous_transaction_id` chain. Returns all versions ordered from newest to oldest.

Required scope: `transactions:read`



## OpenAPI

````yaml get /v1/transactions/{transaction_id}/history
openapi: 3.0.0
info:
  title: Otark BRP API
  description: >-
    API for Balancing Responsible Parties (BRPs) to manage contracts,
    transactions, nominations, and customers on the Otark platform.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.otark.energy
    description: Production
security: []
tags:
  - name: Contracts
    description: Manage energy contracts (PPA, day-ahead, etc.)
  - name: Transactions
    description: Contractual energy volumes between buyer and seller
  - name: Nominations
    description: Net saldo aggregated by balance group
  - name: Customers
    description: Manage customers assigned to the BRP
paths:
  /v1/transactions/{transaction_id}/history:
    get:
      tags:
        - Transactions
      summary: Get transaction history
      description: >-
        Retrieve the full version history of a transaction, following the
        `previous_transaction_id` chain. Returns all versions ordered from
        newest to oldest.


        Required scope: `transactions:read`
      operationId: getTransactionHistory
      parameters:
        - name: transaction_id
          in: path
          required: true
          description: Transaction identifier
          schema:
            type: string
            example: txn_k8m2p4q7r1
        - $ref: '#/components/parameters/IncludeAssetsParam'
      responses:
        '200':
          description: Transaction version history
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionHistoryList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    IncludeAssetsParam:
      name: include_assets
      in: query
      description: >-
        Include a deduplicated `assets` array in the response, containing all
        assets referenced by the returned transactions
      schema:
        type: string
        enum:
          - 'true'
          - 'false'
        default: 'false'
  headers:
    X-RateLimit-Limit:
      description: Maximum number of requests allowed per window
      schema:
        type: integer
        example: 300
    X-RateLimit-Remaining:
      description: Remaining requests in the current window
      schema:
        type: integer
        example: 299
    X-RateLimit-Reset:
      description: Seconds until the rate limit window resets
      schema:
        type: integer
        example: 60
  schemas:
    TransactionHistoryList:
      type: object
      properties:
        transactions:
          type: array
          description: Version history ordered from newest to oldest
          items:
            $ref: '#/components/schemas/Transaction'
        assets:
          type: array
          description: >-
            Deduplicated list of assets referenced by the returned transactions
            (only present when `include_assets=true`)
          items:
            $ref: '#/components/schemas/Asset'
      required:
        - transactions
    Transaction:
      type: object
      description: >-
        Represents the contractual energy volumes to be transferred between
        buyer and seller under a contract. Transactions are immutable —
        corrections produce a new version that supersedes the previous one.
      properties:
        id:
          type: string
          description: Unique transaction identifier
          example: txn_k8m2p4q7r1
        type:
          type: string
          description: Transaction type
          enum:
            - ppa
          example: ppa
        contract_id:
          type: string
          description: Parent contract identifier
          example: con_a1b2c3d4
        status:
          type: string
          description: Transaction status
          enum:
            - valid
            - invalid
            - superseded
          example: valid
        version:
          type: integer
          description: Version number (starts at 1, increments on correction)
          example: 2
        previous_transaction_id:
          type: string
          nullable: true
          description: ID of the transaction this version supersedes
          example: txn_j5n3w8v2x6
        sender:
          $ref: '#/components/schemas/TransactionSender'
        receiver:
          $ref: '#/components/schemas/TransactionReceiver'
        delivery_start:
          type: string
          format: date-time
          description: ISO 8601 delivery period start (UTC)
          example: '2026-01-15T14:00:00Z'
        delivery_end:
          type: string
          format: date-time
          description: ISO 8601 delivery period end (UTC)
          example: '2026-01-15T14:15:00Z'
        slot_number:
          type: integer
          description: >-
            Quarter-hour slot number within the delivery day (1–96, or up to 100
            on DST days)
          minimum: 1
          maximum: 100
          example: 57
        volume:
          type: number
          description: Energy volume in MWh (3 decimal places)
          example: 12.5
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
          example: '2026-01-14T18:00:00Z'
      required:
        - id
        - type
        - contract_id
        - status
        - version
        - sender
        - receiver
        - delivery_start
        - delivery_end
        - slot_number
        - volume
        - created_at
    Asset:
      type: object
      description: A generating asset
      properties:
        id:
          type: string
          description: Unique asset identifier
          example: ast_w1x2y3z4
        name:
          type: string
          description: Display name of the generating asset
          example: Zonnepark De Wilgen
        nominal_power:
          type: number
          description: Nominal power capacity in MW
          example: 25
        technology:
          type: string
          description: Generation technology
          enum:
            - solar
            - wind_onshore
            - wind_offshore
          example: solar
        tso:
          type: string
          description: TSO responsible for the asset's grid connection
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_TENNET
      required:
        - id
        - name
        - nominal_power
        - technology
        - tso
    Problem:
      type: object
      description: >-
        Error response following [RFC 9457 — Problem Details for HTTP
        APIs](https://www.rfc-editor.org/rfc/rfc9457).
      properties:
        type:
          type: string
          format: uri
          description: Absolute URI identifying the problem class
          example: https://brp.otark.team/errors/balance_group_tso_not_enabled
        title:
          type: string
          description: >-
            Short human-readable label (stable across occurrences of the same
            type)
          example: Balance Group TSO Not Enabled
        status:
          type: integer
          description: HTTP status code
          example: 400
        detail:
          type: string
          description: Human-readable explanation for this specific occurrence
          example: >-
            The requested TSO is not enabled for this balance group. Enable it
            via the balance group settings first.
        instance:
          type: string
          description: URI identifying the specific request
          example: /v1/customers/cust_r8s9t0u1
        errors:
          type: array
          description: Field-level validation errors (present on validation failures)
          items:
            $ref: '#/components/schemas/ProblemFieldError'
      required:
        - type
        - title
        - status
    TransactionSender:
      type: object
      description: The sending party of a transaction
      properties:
        eic:
          type: string
          description: EIC code (balance group) of the sender
          example: 11YWINDPARKNO--A
        asset_id:
          type: string
          nullable: true
          description: >-
            Asset identifier (use `include_assets=true` to sideload full asset
            details)
          example: ast_w1x2y3z4
        tso:
          type: string
          description: Sender's TSO
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_TENNET
      required:
        - eic
        - asset_id
        - tso
    TransactionReceiver:
      type: object
      description: The receiving party of a transaction
      properties:
        eic:
          type: string
          description: EIC code (balance group) of the receiver
          example: 11YGREENENERGY-Z
        tso:
          type: string
          description: Receiver's TSO
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_TENNET
      required:
        - eic
        - tso
    ProblemFieldError:
      type: object
      description: A single field-level validation error
      properties:
        field:
          type: string
          description: JSON path of the field that caused the error
          example: balance_group.tso
        code:
          type: string
          description: >-
            Machine-readable error code: `unknown_field`, `read_only_field`,
            `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`,
            `invalid_literal`, `value_too_small`, `value_too_large`, or
            `validation_failed`
          example: invalid_enum_value
        message:
          type: string
          description: Human-readable description of the issue
          example: >-
            Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' |
            'DE_TRANSNET_BW' | 'DE_50HERTZ', received 'INVALID'
      required:
        - code
        - message
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://brp.otark.team/errors/invalid_api_key
            title: Invalid API Key
            status: 401
    Forbidden:
      description: API key lacks required scopes
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://brp.otark.team/errors/insufficient_scopes
            title: Insufficient API Key Scopes
            status: 403
            detail: >-
              Missing scope: customers:write. Please create a new API key with
              the required scopes.
    NotFound:
      description: Resource does not exist or caller has no access
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://brp.otark.team/errors/customer_not_found
            title: Customer Not Found
            status: 404
            instance: /v1/customers/cust_r8s9t0u1
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

````