> ## 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 reports

> Every report in the workspace, by name, with its widgets: private reports included, which in the app only their owner sees. A widget that runs SQL carries it; one made with the visual query builder does not.



## OpenAPI

````yaml /api/statisfy-api.openapi.json get /v1/reports
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/reports:
    get:
      tags:
        - reports
      summary: List reports
      description: >-
        Every report in the workspace, by name, with its widgets: private
        reports included, which in the app only their owner sees. A widget that
        runs SQL carries it; one made with the visual query builder does not.
      operationId: reports_list
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsResponse'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    ReportsResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Report'
          title: Data
          type: array
      required:
        - data
      title: ReportsResponse
      type: object
    Report:
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        id:
          title: Id
          type: string
        name:
          description: Unique across the workspace
          title: Name
          type: string
        owner:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The owner's email: besides admins, only the owner can change it in
            the app. Null when it has no owner, or its owner is no longer a user
          title: Owner
        updated_at:
          format: date-time
          title: Updated At
          type: string
        visibility:
          description: >-
            team (Public in the app: everyone in the workspace sees it on the
            reports page) or private (only its owner sees it there; admins can
            change it but don't see it listed). The API lists both
          enum:
            - team
            - private
          title: Visibility
          type: string
        widgets:
          items:
            $ref: '#/components/schemas/ReportWidget'
          title: Widgets
          type: array
      required:
        - id
        - name
        - description
        - visibility
        - owner
        - widgets
        - created_at
        - updated_at
      title: Report
      type: object
    ReportWidget:
      properties:
        built_with:
          description: >-
            sql (it runs SQL: `sql` holds it), builder (made with the visual
            query builder; the API doesn't return its query), or text (a text
            widget: `text` holds it)
          enum:
            - sql
            - builder
            - text
          title: Built With
          type: string
        chart:
          $ref: '#/components/schemas/ReportChart'
        id:
          title: Id
          type: string
        markdown:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            A text widget's Markdown option: true shows `text` as Markdown,
            false as plain text
          title: Markdown
        position:
          anyOf:
            - $ref: '#/components/schemas/ReportWidgetPosition'
            - type: 'null'
          description: >-
            Where it sits on the report's grid; null if what's stored can't be
            read
        sql:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The widget's SQL as saved in the app: it may have comments or your
            workspace's schema name. On the reports page it runs with the
            report's filters and the viewer's scope added, under the app's own
            checks, so POST /v1/reports/query may refuse it or return different
            rows
          title: Sql
        text:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A text widget's content. The app shows it as Markdown when the
            widget's Markdown option is on (new text widgets have it on),
            otherwise as plain text
          title: Text
        title:
          title: Title
          type: string
        type:
          description: >-
            metric, bar_chart, line_chart, area_chart, pie_chart, scatter_chart,
            table or text
          title: Type
          type: string
      required:
        - id
        - title
        - type
        - built_with
        - chart
        - position
      title: ReportWidget
      type: object
    ReportChart:
      description: A widget's display settings, as the reports page stores them.
      properties:
        colors:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: The palette, as CSS colors
          title: Colors
        compact_notation:
          anyOf:
            - enum:
                - K
                - M
                - B
                - T
              type: string
            - type: 'null'
          title: Compact Notation
        currency_symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency Symbol
        decimal_digits:
          anyOf:
            - maximum: 20
              minimum: 0
              type: integer
            - type: 'null'
          title: Decimal Digits
        max_series:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          description: Show the top N series by total
          title: Max Series
        orientation:
          anyOf:
            - enum:
                - vertical
                - horizontal
              type: string
            - type: 'null'
          title: Orientation
        page_size:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          description: A table's rows per page
          title: Page Size
        pivot_column:
          anyOf:
            - type: string
            - type: 'null'
          description: A table's column whose values become columns
          title: Pivot Column
        series_column:
          anyOf:
            - type: string
            - type: 'null'
          description: A column whose values split the data into series
          title: Series Column
        show_data_labels:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Show Data Labels
        show_legend:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Show Legend
        stacked:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Stacked
        value_column:
          anyOf:
            - type: string
            - type: 'null'
          description: The column a pivot spreads
          title: Value Column
        value_format:
          anyOf:
            - enum:
                - number
                - currency
                - percent
                - compact
              type: string
            - type: 'null'
          description: 'How the widget''s values read: a metric''s value, a chart''s axis'
          title: Value Format
        x_axis:
          anyOf:
            - type: string
            - type: 'null'
          description: The column on the x axis
          title: X Axis
        y_axis:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: The columns plotted, one series each
          title: Y Axis
      title: ReportChart
      type: object
    ReportWidgetPosition:
      properties:
        h:
          description: Height, in rows
          minimum: 1
          title: H
          type: integer
        w:
          description: Width, in columns
          minimum: 1
          title: W
          type: integer
        x:
          description: Columns from the left of the report's grid
          minimum: 0
          title: X
          type: integer
        'y':
          description: Rows from the top
          minimum: 0
          title: 'Y'
          type: integer
      required:
        - x
        - 'y'
        - w
        - h
      title: ReportWidgetPosition
      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.