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

# List a product's usage values

> Pages through a product's usage rows, newest date first, each with the values of the product's dimensions, hidden ones included. Filter with `filter[<key>][<op>]=<value>` (conditions are ANDed; `in` repeats the parameter): `account` (eq, in: up to 100 Statisfy account ids), taking one condition, and `date` (eq, gt, gte, lt, lte: YYYY-MM-DD), which takes several. A filter's date is not moved to its period's first day, so on a WEEKLY product `filter[date][eq]` matches a row only on the week's first day: use gte and lt for a range. `limit` is up to 1000. Values a pillar breaks down (the app's by-pillar view) are not listed. Usage values are what a product's dimensions measure, per account and date, at the product's period (its `period`; the app shows usage at no other, and a product with none set shows at MONTHLY). A write moves a date to its period's first day: for WEEKLY, the weekday the product's latest weekly row falls on (Monday when it has none); the 1st for MONTHLY; the first day of the quarter for QUARTERLY (in the product's quarter cycle; calendar quarters when it has no rows), and January 1 for YEARLY; DAILY and SINGLE keep the date sent. An account has one row per date here: where data feeds stored several (older rows, or a CSV feed set to allow multiple rows per customer), the one written and listed is the row the feeds write today, else the oldest, while the app shows them all. A product with no display settings, or a period this API does not know, is a 409.



## OpenAPI

````yaml /api/statisfy-api.openapi.json get /v1/products/{product_id}/usage
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/products/{product_id}/usage:
    get:
      tags:
        - usage
      summary: List a product's usage values
      description: >-
        Pages through a product's usage rows, newest date first, each with the
        values of the product's dimensions, hidden ones included. Filter with
        `filter[<key>][<op>]=<value>` (conditions are ANDed; `in` repeats the
        parameter): `account` (eq, in: up to 100 Statisfy account ids), taking
        one condition, and `date` (eq, gt, gte, lt, lte: YYYY-MM-DD), which
        takes several. A filter's date is not moved to its period's first day,
        so on a WEEKLY product `filter[date][eq]` matches a row only on the
        week's first day: use gte and lt for a range. `limit` is up to 1000.
        Values a pillar breaks down (the app's by-pillar view) are not listed.
        Usage values are what a product's dimensions measure, per account and
        date, at the product's period (its `period`; the app shows usage at no
        other, and a product with none set shows at MONTHLY). A write moves a
        date to its period's first day: for WEEKLY, the weekday the product's
        latest weekly row falls on (Monday when it has none); the 1st for
        MONTHLY; the first day of the quarter for QUARTERLY (in the product's
        quarter cycle; calendar quarters when it has no rows), and January 1 for
        YEARLY; DAILY and SINGLE keep the date sent. An account has one row per
        date here: where data feeds stored several (older rows, or a CSV feed
        set to allow multiple rows per customer), the one written and listed is
        the row the feeds write today, else the oldest, while the app shows them
        all. A product with no display settings, or a period this API does not
        know, is a 409.
      operationId: usage_list
      parameters:
        - in: path
          name: product_id
          required: true
          schema:
            type: string
        - in: query
          name: limit
          required: false
          schema:
            default: 100
            maximum: 1000
            minimum: 1
            type: integer
        - description: '`next_cursor` from the previous page'
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            default: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsagePage'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    UsagePage:
      properties:
        data:
          items:
            $ref: '#/components/schemas/UsageRow'
          title: Data
          type: array
        has_more:
          default: false
          title: Has More
          type: boolean
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      required:
        - data
      title: UsagePage
      type: object
    UsageRow:
      properties:
        account:
          description: The Statisfy account id
          title: Account
          type: string
        date:
          description: >-
            The day the row is stored under: the period's first day for rows
            written here (a feed that counts weeks or quarters differently dates
            its rows by its own calendar)
          format: date
          title: Date
          type: string
        values:
          additionalProperties:
            anyOf:
              - type: number
              - type: boolean
              - type: string
          description: >-
            The product's dimension key → value; a date value is YYYY-MM-DD. A
            key is absent when the row holds no value its dimension's type reads
            (none stored, or one a data feed stored in another form, which the
            app shows as No Data)
          title: Values
          type: object
      required:
        - account
        - date
        - values
      title: UsageRow
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

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