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

# Run report SQL

> Runs your SQL over the report views and returns its rows (up to `limit`, at most 1000). Send one SELECT (WITH, UNION, INTERSECT and EXCEPT are fine) over the report views `GET /v1/reports/sources` lists, named without a schema. Only listed functions run: aggregates; window functions; common date, number, text, array and conditional functions; and JSON field access (->, ->>, #>, #>>). JSON-building functions (such as json_agg) and operators such as ~*, @> and && aren't available. Any other function, a table that isn't a report view, another schema, or a setting is refused with a 422 listing each problem. It runs read-only with the time zone set to UTC, stops after about 15 seconds (a 504), and refuses a result over 32 MB or a row over 4 MB (a 422). Your workspace runs a few report queries at once on each server; one past that waits a few seconds, then is a 429 with Retry-After. lpad and rpad take a length of at most 10000, written as a number. SQL the database refuses (a missing column, a bad cast) is a 422 with Postgres's message. These are the API's own rules: the reports page runs a widget's SQL with the report's filters and the viewer's scope added, allows it 30 seconds, and checks SQL its own way, so results and refusals can differ. Safe to retry: it only reads.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/reports/query
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/query:
    post:
      tags:
        - reports
      summary: Run report SQL
      description: >-
        Runs your SQL over the report views and returns its rows (up to `limit`,
        at most 1000). Send one SELECT (WITH, UNION, INTERSECT and EXCEPT are
        fine) over the report views `GET /v1/reports/sources` lists, named
        without a schema. Only listed functions run: aggregates; window
        functions; common date, number, text, array and conditional functions;
        and JSON field access (->, ->>, #>, #>>). JSON-building functions (such
        as json_agg) and operators such as ~*, @> and && aren't available. Any
        other function, a table that isn't a report view, another schema, or a
        setting is refused with a 422 listing each problem. It runs read-only
        with the time zone set to UTC, stops after about 15 seconds (a 504), and
        refuses a result over 32 MB or a row over 4 MB (a 422). Your workspace
        runs a few report queries at once on each server; one past that waits a
        few seconds, then is a 429 with Retry-After. lpad and rpad take a length
        of at most 10000, written as a number. SQL the database refuses (a
        missing column, a bad cast) is a 422 with Postgres's message. These are
        the API's own rules: the reports page runs a widget's SQL with the
        report's filters and the viewer's scope added, allows it 30 seconds, and
        checks SQL its own way, so results and refusals can differ. Safe to
        retry: it only reads.
      operationId: reports_query
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                limit:
                  default: 100
                  description: The most rows to return
                  maximum: 1000
                  minimum: 1
                  title: Limit
                  type: integer
                sql:
                  description: >-
                    Send one SELECT (WITH, UNION, INTERSECT and EXCEPT are fine)
                    over the report views `GET /v1/reports/sources` lists, named
                    without a schema. Only listed functions run: aggregates;
                    window functions; common date, number, text, array and
                    conditional functions; and JSON field access (->, ->>, #>,
                    #>>). JSON-building functions (such as json_agg) and
                    operators such as ~*, @> and && aren't available. Any other
                    function, a table that isn't a report view, another schema,
                    or a setting is refused with a 422 listing each problem.
                  maxLength: 20000
                  minLength: 1
                  title: Sql
                  type: string
              required:
                - sql
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportQueryResult'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    ReportQueryResult:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/ReportQueryColumn'
          title: Columns
          type: array
        rows:
          description: Each row's values, in the columns' order
          items:
            items: {}
            type: array
          title: Rows
          type: array
        sql:
          description: >-
            Your statement as it ran: checked, without comments or your
            workspace's schema name, and with some spellings normalized (now()
            reads CURRENT_TIMESTAMP, x::text reads CAST(x AS TEXT)). `limit` is
            applied around it
          title: Sql
          type: string
        truncated:
          description: Whether the query had more rows than `limit`
          title: Truncated
          type: boolean
      required:
        - sql
        - columns
        - rows
        - truncated
      title: ReportQueryResult
      type: object
    ReportQueryColumn:
      properties:
        name:
          title: Name
          type: string
        type:
          description: >-
            How its values come. number: a JSON number (numeric as floating
            point; NaN, Infinity and numbers beyond a float's range as null).
            date, time, timestamp: ISO 8601 (a timestamp with a time zone in
            UTC, +00:00; one without, as stored). interval: seconds (a month
            counts as 30 days, a year as 365). json: JSON. uuid: text. array: a
            JSON array. text, boolean as such; other: text
          enum:
            - number
            - text
            - boolean
            - date
            - timestamp
            - time
            - interval
            - json
            - uuid
            - array
            - other
          title: Type
          type: string
      required:
        - name
        - type
      title: ReportQueryColumn
      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.