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

# Get a forecast



## OpenAPI

````yaml /openapi/v1.yaml get /forecasts/{id}
openapi: 3.1.0
info:
  title: ThinkOut API
  version: '1.0'
  description: >
    Read access to the data of a ThinkOut workspace.


    Every endpoint in version 1 is a `GET`. Lists share one envelope and page
    with a cursor

    wherever they can grow. Every response carries `X-RateLimit-Limit`,
    `X-RateLimit-Remaining`

    and `X-RateLimit-Reset`.


    Version 1 changes additively: new endpoints, optional parameters, response
    fields and enum

    values can appear at any time. Tolerate unknown fields and never treat an
    enum as closed.
  contact:
    name: ThinkOut developer support
    url: https://developers.thinkout.io/guides/support
servers:
  - url: https://api.thinkout.io/v1
security:
  - apiKey: []
tags:
  - name: Banks
    description: The workspace's bank connections and the state of each one.
  - name: Accounts
    description: Manual, bank-synced and delegated accounts with computed balances.
  - name: Transactions
    description: Booked and pending movements on the workspace's accounts.
  - name: Categories
    description: The workspace category tree, split by direction and business activity.
  - name: Counterparties
    description: Customers and suppliers that transactions and forecasts are attributed to.
  - name: Labels
    description: Free-form tags grouped by label type.
  - name: Forecasts
    description: Planned inflows and outflows and the transactions that realised them.
  - name: Reports
    description: >-
      Totals rather than rows. Summaries over transactions, forecasts and cash
      flow, and balances per account.
paths:
  /forecasts/{id}:
    get:
      tags:
        - Forecasts
      summary: Get a forecast
      operationId: getForecast
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/forecast_expand'
      responses:
        '200':
          description: The forecast.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forecast'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    forecast_expand:
      name: expand
      in: query
      description: >-
        Relations to return as objects instead of ids. Comma-separated.
        Expansion goes one level deep; an unknown name is rejected with
        `invalid_expand`.
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - category
            - counterparty
            - labels
            - recurrence
            - linked_transactions
      example: category,linked_transactions
  schemas:
    Forecast:
      type: object
      required:
        - object
        - id
        - date
        - amount
        - remaining_amount
        - currency
        - direction
        - status
        - description
        - comment
        - category
        - counterparty
        - labels
        - recurrence
        - linked_transactions
        - created_at
        - updated_at
      properties:
        object:
          type: string
          const: forecast
        id:
          type: string
          format: uuid
        date:
          type: string
          format: date
          description: The day the movement is expected.
        amount:
          $ref: '#/components/schemas/Money'
        remaining_amount:
          $ref: '#/components/schemas/Money'
          description: The part of `amount` not yet matched by linked transactions.
        currency:
          $ref: '#/components/schemas/Currency'
        direction:
          $ref: '#/components/schemas/Direction'
        status:
          $ref: '#/components/schemas/ForecastStatus'
        description:
          type:
            - string
            - 'null'
        comment:
          type:
            - string
            - 'null'
        category:
          $ref: '#/components/schemas/ExpandableCategory'
        counterparty:
          $ref: '#/components/schemas/ExpandableCounterparty'
        labels:
          $ref: '#/components/schemas/ExpandableLabels'
        recurrence:
          $ref: '#/components/schemas/ExpandableRecurrence'
        linked_transactions:
          type: array
          description: >-
            Transactions matched to this forecast, as ids, or as transactions
            when `linked_transactions` is named in `expand`.
          items:
            oneOf:
              - type: string
                format: uuid
              - $ref: '#/components/schemas/Transaction'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        object: forecast
        id: 7e6d5c4b-3a29-4180-9f8e-7d6c5b4a3928
        date: '2026-09-15'
        amount: '-4200.00'
        remaining_amount: '-4200.00'
        currency: EUR
        direction: outflow
        status: planned
        description: Office rent
        comment: null
        category: 2a3b4c5d-6e7f-4809-8a1b-2c3d4e5f6a7b
        counterparty: 8b9c0d1e-2f3a-4b5c-8d6e-7f8a9b0c1d2e
        labels:
          - 0f1e2d3c-4b5a-4968-8776-655443322110
        recurrence: 4c5d6e7f-8091-4a2b-9c3d-4e5f6a7b8c9d
        linked_transactions: []
        created_at: '2025-12-20T09:30:00Z'
        updated_at: '2025-12-20T09:30:00Z'
    Money:
      type: string
      description: >-
        Decimal amount as a string with two decimals. Negative means an outflow
        on transactions, forecasts and report figures.
      pattern: ^-?[0-9]+\.[0-9]{2}$
      example: '-1250.00'
    Currency:
      type: string
      description: ISO 4217 alphabetic currency code.
      pattern: ^[A-Z]{3}$
      example: RON
    Direction:
      type: string
      description: >-
        Whether money comes in or goes out. On a transaction or forecast it
        follows the sign of `amount`.
      enum:
        - inflow
        - outflow
    ForecastStatus:
      type: string
      description: >-
        `realised` is complete. `partial` has matched transactions. `overdue` is
        dated before today with none. `planned` is dated today or later with
        none.
      enum:
        - planned
        - overdue
        - partial
        - realised
    ExpandableCategory:
      description: A category id, or the full category when named in `expand`.
      oneOf:
        - type: string
          format: uuid
        - $ref: '#/components/schemas/Category'
    ExpandableCounterparty:
      description: >-
        A counterparty id, the full counterparty when named in `expand`, or
        `null` when unattributed.
      oneOf:
        - type: string
          format: uuid
        - $ref: '#/components/schemas/Counterparty'
        - type: 'null'
    ExpandableLabels:
      description: Label ids, or the full labels when `labels` is named in `expand`.
      type: array
      items:
        oneOf:
          - type: string
            format: uuid
          - $ref: '#/components/schemas/Label'
    ExpandableRecurrence:
      description: >-
        The id of the recurring plan the forecast was generated from, the full
        plan when named in `expand`, or `null` for a one-off forecast.
      oneOf:
        - type: string
          format: uuid
        - $ref: '#/components/schemas/Recurrence'
        - type: 'null'
    Transaction:
      type: object
      required:
        - object
        - id
        - date
        - amount
        - currency
        - direction
        - status
        - source
        - description
        - comment
        - account
        - category
        - counterparty
        - labels
        - bank_details
        - created_at
        - updated_at
      properties:
        object:
          type: string
          const: transaction
        id:
          type: string
          format: uuid
        date:
          type: string
          format: date
          description: Booking date. There is no time component.
          example: '2026-09-03'
        amount:
          $ref: '#/components/schemas/Money'
        currency:
          $ref: '#/components/schemas/Currency'
        direction:
          $ref: '#/components/schemas/Direction'
        status:
          $ref: '#/components/schemas/TransactionStatus'
        source:
          $ref: '#/components/schemas/TransactionSource'
        description:
          type:
            - string
            - 'null'
          example: ORANGE ROMANIA SA
        comment:
          type:
            - string
            - 'null'
          description: Free text added by users in ThinkOut.
        account:
          $ref: '#/components/schemas/ExpandableAccount'
        category:
          oneOf:
            - $ref: '#/components/schemas/ExpandableCategory'
            - type: 'null'
          description: >-
            `null` for a split transaction, whose categorisation lives on its
            pieces.
        counterparty:
          $ref: '#/components/schemas/ExpandableCounterparty'
        labels:
          $ref: '#/components/schemas/ExpandableLabels'
        bank_details:
          oneOf:
            - $ref: '#/components/schemas/BankDetails'
            - type: 'null'
          description: '`null` unless `source` is `bank`.'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        object: transaction
        id: 8f1c0a4e-2b1d-4c8e-9f3a-7d6e5c4b3a21
        date: '2026-09-03'
        amount: '-1250.00'
        currency: RON
        direction: outflow
        status: booked
        source: bank
        description: ORANGE ROMANIA SA
        comment: null
        account: c2d7e8f9-1a2b-4c3d-8e9f-0a1b2c3d4e5f
        category: 3b4c5d6e-7f80-4a1b-9c2d-3e4f5a6b7c8d
        counterparty: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
        labels:
          - 1f2e3d4c-5b6a-4978-8877-665544332211
        bank_details:
          payer: THINKOUT SRL
          payer_details: RO49INGB0000999900000001
          payee: ORANGE ROMANIA SA
          payee_details: RO12BTRL0000000000000002
          reference: Factura 2026-08 nr 1234567
          additional: null
        created_at: '2026-09-03T08:12:44Z'
        updated_at: '2026-09-03T08:12:44Z'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - param
            - request_id
          properties:
            type:
              type: string
              enum:
                - invalid_request
                - authentication
                - not_found
                - rate_limit
                - server
            code:
              type: string
              description: >
                Stable machine-readable reason. Branch on this, not on
                `message`. One of

                `invalid_parameter`, `invalid_cursor`, `limit_out_of_range`,
                `invalid_expand`,

                `as_of_in_future`, `unauthorized`, `forbidden`,
                `resource_not_found`,

                `too_many_groups`, `period_too_long`, `rate_limited`,
                `internal_error`.
            message:
              type: string
              description: Human-readable explanation. Wording may change.
            param:
              type:
                - string
                - 'null'
              description: The query parameter at fault, when there is one.
            request_id:
              type: string
              description: Quote this when contacting support.
    Category:
      type: object
      required:
        - object
        - id
        - name
        - code
        - direction
        - activity
        - parent_id
        - position
        - color
        - created_at
        - updated_at
      properties:
        object:
          type: string
          const: category
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Telecom
        code:
          type:
            - string
            - 'null'
          description: >-
            The category's identifier in the template the workspace was created
            from, or `null` for a category someone created. Only
            `uncategorized_inflows` and `uncategorized_outflows` exist in every
            workspace and are worth branching on.
          example: uncategorized_outflows
        direction:
          $ref: '#/components/schemas/Direction'
        activity:
          $ref: '#/components/schemas/Activity'
        parent_id:
          type:
            - string
            - 'null'
          format: uuid
          description: '`null` for top-level categories.'
        position:
          type: integer
          description: Order among siblings, as shown in ThinkOut.
        color:
          type:
            - string
            - 'null'
          description: Lowercase hex color as shown in ThinkOut.
          pattern: ^#[0-9a-f]{6}$
          example: '#1b7fe4'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        object: category
        id: 3b4c5d6e-7f80-4a1b-9c2d-3e4f5a6b7c8d
        name: Telecom
        code: null
        direction: outflow
        activity: operating
        parent_id: 6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d
        position: 2
        color: '#1b7fe4'
        created_at: '2024-01-01T10:00:00Z'
        updated_at: '2024-01-01T10:00:00Z'
    Counterparty:
      type: object
      required:
        - object
        - id
        - name
        - country_code
        - color
        - symbol
        - created_at
        - updated_at
      properties:
        object:
          type: string
          const: counterparty
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Orange
        country_code:
          type:
            - string
            - 'null'
          description: ISO 3166-1 alpha-2 country code.
          pattern: ^[A-Z]{2}$
          example: RO
        color:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
        symbol:
          type:
            - string
            - 'null'
          description: Short text shown in the counterparty avatar in ThinkOut.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        object: counterparty
        id: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
        name: Orange
        country_code: RO
        color: '#e4571b'
        symbol: OR
        created_at: '2024-02-14T08:00:00Z'
        updated_at: '2024-02-14T08:00:00Z'
    Label:
      type: object
      required:
        - object
        - id
        - name
        - type
        - color
        - created_at
        - updated_at
      properties:
        object:
          type: string
          const: label
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Q3
        type:
          oneOf:
            - $ref: '#/components/schemas/LabelType'
            - type: 'null'
          description: >-
            The group this label belongs to, or `null` when ungrouped. Types
            have no endpoint of their own.
        color:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-f]{6}$
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        object: label
        id: 1f2e3d4c-5b6a-4978-8877-665544332211
        name: Q3
        type:
          id: 7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f
          name: Quarter
        color: '#7c3aed'
        created_at: '2026-01-05T09:00:00Z'
        updated_at: '2026-01-05T09:00:00Z'
    Recurrence:
      type: object
      description: The recurring plan this forecast was generated from.
      required:
        - id
        - name
        - interval
        - every
        - start_date
        - end_date
        - occurrences
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Office rent
        interval:
          $ref: '#/components/schemas/RecurrenceInterval'
        every:
          type: integer
          minimum: 1
          description: >-
            Number of intervals between occurrences. `interval: month, every: 1`
            is monthly.
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        occurrences:
          type: integer
          description: Total number of forecasts generated by the plan.
    TransactionStatus:
      type: string
      description: >-
        `pending` transactions come from a bank and are not yet booked. Their
        amount can change when they book, so upsert by `id`.
      enum:
        - booked
        - pending
    TransactionSource:
      type: string
      description: How the transaction entered ThinkOut.
      enum:
        - manual
        - import
        - bank
    ExpandableAccount:
      description: An account id, or the full account when named in `expand`.
      oneOf:
        - type: string
          format: uuid
        - $ref: '#/components/schemas/Account'
    BankDetails:
      type: object
      description: Raw fields received from the bank.
      required:
        - payer
        - payer_details
        - payee
        - payee_details
        - reference
        - additional
      properties:
        payer:
          type:
            - string
            - 'null'
        payer_details:
          type:
            - string
            - 'null'
          description: Payer account identifiers as provided by the bank.
        payee:
          type:
            - string
            - 'null'
        payee_details:
          type:
            - string
            - 'null'
        reference:
          type:
            - string
            - 'null'
          description: Payment reference or information line.
        additional:
          type:
            - string
            - 'null'
    Activity:
      type: string
      description: Cash flow statement section the category belongs to.
      enum:
        - operating
        - investing
        - financing
    LabelType:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Quarter
    RecurrenceInterval:
      type: string
      enum:
        - day
        - week
        - month
        - year
    Account:
      type: object
      required:
        - object
        - id
        - name
        - currency
        - group
        - source
        - balance
        - balance_as_of
        - opening_balance
        - opening_date
        - bank
        - external_account_id
        - original_name
        - created_at
        - updated_at
      properties:
        object:
          type: string
          const: account
        id:
          type: string
          format: uuid
        name:
          type: string
          example: ING Curent
        currency:
          $ref: '#/components/schemas/Currency'
        group:
          type:
            - string
            - 'null'
          description: Free-text grouping assigned in ThinkOut.
          example: Operational
        source:
          $ref: '#/components/schemas/AccountSource'
        balance:
          $ref: '#/components/schemas/Money'
        balance_as_of:
          type: string
          format: date
          description: The day whose end-of-day balance is reported.
        opening_balance:
          $ref: '#/components/schemas/Money'
        opening_date:
          type: string
          format: date
          description: The date the opening balance applies to.
        bank:
          $ref: '#/components/schemas/ExpandableBank'
        external_account_id:
          type:
            - string
            - 'null'
          description: The account identifier at the provider. `null` for manual accounts.
        original_name:
          type:
            - string
            - 'null'
          description: >-
            The account name as the bank reports it, before any rename in
            ThinkOut. `null` for manual accounts.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        object: account
        id: c2d7e8f9-1a2b-4c3d-8e9f-0a1b2c3d4e5f
        name: ING Curent
        currency: RON
        group: Operational
        source: bank
        balance: '15230.45'
        balance_as_of: '2026-09-03'
        opening_balance: '1000.00'
        opening_date: '2024-01-01'
        bank: 5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f
        external_account_id: ACC-00012345
        original_name: Cont curent RON
        created_at: '2024-01-01T10:00:00Z'
        updated_at: '2026-08-30T06:00:00Z'
    AccountSource:
      type: string
      description: >-
        `delegated` accounts are bank accounts another workspace has delegated
        to this one.
      enum:
        - manual
        - bank
        - delegated
    ExpandableBank:
      description: >-
        A bank connection id, the full connection when named in `expand`, or
        `null` for a manual account. On a `delegated` account the connection
        belongs to another workspace, so the id is returned but is neither
        expanded nor readable.
      oneOf:
        - type: string
          format: uuid
        - $ref: '#/components/schemas/Bank'
        - type: 'null'
    Bank:
      type: object
      description: >-
        One authorisation with one bank. Several accounts can share a
        connection, and a workspace can hold several connections to the same
        bank.
      required:
        - object
        - id
        - name
        - country_code
        - status
        - last_sync_at
        - consent_expires_at
        - created_at
        - updated_at
      properties:
        object:
          type: string
          const: bank
        id:
          type: string
          format: uuid
        name:
          type: string
          description: The bank's name as the provider reports it.
          example: ING Bank
        country_code:
          type:
            - string
            - 'null'
          description: ISO 3166-1 alpha-2 country of the bank.
          pattern: ^[A-Z]{2}$
          example: RO
        status:
          $ref: '#/components/schemas/BankStatus'
        last_sync_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the provider last returned data successfully, or `null`. A
            `connected` connection with an old `last_sync_at` is the case worth
            alerting on.
        consent_expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the bank consent needs renewal, if the provider reports it.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      example:
        object: bank
        id: 5d6e7f80-9a1b-4c2d-8e3f-4a5b6c7d8e9f
        name: ING Bank
        country_code: RO
        status: connected
        last_sync_at: '2026-09-03T06:00:00Z'
        consent_expires_at: '2026-11-30T00:00:00Z'
        created_at: '2024-01-01T10:00:00Z'
        updated_at: '2026-09-03T06:00:00Z'
    BankStatus:
      type: string
      description: >
        `connected` is working. `loading` is a sync in progress.
        `requires_action` needs a

        person to sign in or re-approve the connection in ThinkOut. `error` is
        any other

        failure. Only `connected` means the data behind it is current.
      enum:
        - connected
        - loading
        - requires_action
        - error
  responses:
    BadRequest:
      description: A parameter is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request
              code: invalid_parameter
              message: direction must be 'inflow' or 'outflow'
              param: direction
              request_id: 0HNF8K3QJL2VM:00000001
    Unauthorized:
      description: The API key is missing, malformed, unknown or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: authentication
              code: unauthorized
              message: Missing, malformed, unknown or revoked API key
              param: null
              request_id: 0HNF8K3QJL2VM:00000001
    Forbidden:
      description: >-
        The key is valid but the company's ThinkOut plan does not include the
        API.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: authentication
              code: forbidden
              message: >-
                The API is not included in this company's ThinkOut plan. Contact
                support@thinkout.io to enable it.
              param: null
              request_id: 0HNF8K3QJL2VM:00000001
    NotFound:
      description: No object with this id exists in the key's workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: not_found
              code: resource_not_found
              message: Transaction not found
              param: null
              request_id: 0HNF8K3QJL2VM:00000001
    RateLimited:
      description: >-
        More than 120 requests in the current minute for this key. Wait for the
        seconds in `Retry-After`.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the minute window resets.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Requests allowed per minute.
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests left in the current minute.
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until the minute window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: rate_limit
              code: rate_limited
              message: Too many requests
              param: null
              request_id: 0HNF8K3QJL2VM:00000001
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A workspace API key created in ThinkOut settings. One key reads one
        workspace.

````

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