---
title: "Retrieve a Product's books"
method: GET
path: "/v1/products/{productId}/books"
tags: ["Products"]
---

# Retrieve a Product's books

`GET /v1/products/{productId}/books`

## Request

- Base URL: `https://hyperscale0.ai`
- URL: `https://hyperscale0.ai/v1/products/{productId}/books`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

One read for a Product's money: cash and claims now, revenue to date, and earnings, payouts, Hyperscale fees and gross revenue by business month. The months use the same posted figures as the company finance report narrowed to this Product; sandbox months use the Product's business time. Amounts are minor-unit strings.

## Path parameters

- `productId` string, required: Hyperscale product ID

## Query parameters

- `fromPeriod` string: First business month. With neither month, the books run from the first posting to the Product clock's month, at most 24 months.
- `toPeriod` string: Last business month.

## Headers

- `X-Hyperscale-Environment` 'sandbox' | 'live'

## Response `200`

Success

- ProductBooksRetrieveOutput
  - `environment` 'sandbox' | 'live', required
  - `tenantId` string, required: Organization tenant ID
  - `productId` string, required: Hyperscale product ID
  - `asOf` string, date-time, required: When the books hold. In sandbox this is the Product clock, which can run ahead of wall time.
  - `observedAt` string, date-time, required: Wall time of the read.
  - `currency` 'SAR', required
  - `complete` boolean, required: False when a figure below is withheld. unavailable says why.
  - `unavailable` object[], required
    - `code` string, required
    - `message` string, required
    - `period` string: UTC calendar month in YYYY-MM form
  - `position` object, required: Cash and claims now, from one ledger snapshot: what the company can spend, what it holds back, what it holds for customers, what it owes and what customers owe it.
    - `companyAvailable` string, nullable, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `companyHeld` string, nullable, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `heldForCustomers` string, nullable, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `amountsDue` string, nullable, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `receivables` string, nullable, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
  - `revenueToDate` string, required: Posted earnings net of reversals since the Product started, in minor units.
  - `fromPeriod` string, required: UTC calendar month in YYYY-MM form
  - `toPeriod` string, required: UTC calendar month in YYYY-MM form
  - `earlier` object: Older months a default range left out. Pass them as fromPeriod and toPeriod to read them.
    - `fromPeriod` string, required: UTC calendar month in YYYY-MM form
    - `toPeriod` string, required: UTC calendar month in YYYY-MM form
  - `months` object[], required: One row per business month with postings, oldest first.
    - `postedCount` integer, required: Distinct posted finance effects in the breakdown. Capital and pass-through movements are excluded.
    - `revenue` string, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `participantPayouts` string, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `hyperscaleFees` string, required: Activation fees and collected usage invoices, posted from the company credit account. A usage invoice counts once collected. Hyperscale's share of fees collected at execution is paid by the customer and never counts as the company's revenue or cost.
    - `totalCosts` string, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `grossRevenue` string, nullable, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `period` string, required: UTC calendar month in YYYY-MM form
    - `complete` boolean, required
  - `totals` object, required
    - `postedCount` integer, required: Distinct posted finance effects in the breakdown. Capital and pass-through movements are excluded.
    - `revenue` string, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `participantPayouts` string, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `hyperscaleFees` string, required: Activation fees and collected usage invoices, posted from the company credit account. A usage invoice counts once collected. Hyperscale's share of fees collected at execution is paid by the customer and never counts as the company's revenue or cost.
    - `totalCosts` string, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)
    - `grossRevenue` string, nullable, required: Signed minor-unit integer amount serialized as a string (at most 18 digits)

## Other responses

- `default`: ErrorResponse. See x-error-codes and x-errors for codes, HTTP statuses and retry guidance.

---

[API](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api.md) · [All operations](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperscale0/apis/hyperscale-product-api/revisions/e9e8faa044d5?raw)