> ## 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 SQL against the warehouse

> Runs one SELECT against the customer's warehouse, from Statisfy's egress IPs, and returns its rows (up to `limit`, at most 1000). The SQL must stay inside the table allowlist. Date placeholders take the latest complete `period` (weekly by default) or `start_date`/`end_date`. The session is read-only where the warehouse allows it; the warehouse stops the query at 120 seconds (a 504), and BigQuery refuses a scan over `max_bytes_billed` (10 GB unless set in the config). SQL the warehouse refuses is a 422 with its message; a result over 8 MB is a 422 too. Each tenant runs a couple of these at once per server: past that, a 429 with Retry-After. Needs integrations:write: the rows can be anything the warehouse login can read.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/integrations/{key}/sql
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/integrations/{key}/sql:
    post:
      tags:
        - integrations
      summary: Run SQL against the warehouse
      description: >-
        Runs one SELECT against the customer's warehouse, from Statisfy's egress
        IPs, and returns its rows (up to `limit`, at most 1000). The SQL must
        stay inside the table allowlist. Date placeholders take the latest
        complete `period` (weekly by default) or `start_date`/`end_date`. The
        session is read-only where the warehouse allows it; the warehouse stops
        the query at 120 seconds (a 504), and BigQuery refuses a scan over
        `max_bytes_billed` (10 GB unless set in the config). SQL the warehouse
        refuses is a 422 with its message; a result over 8 MB is a 422 too. Each
        tenant runs a couple of these at once per server: past that, a 429 with
        Retry-After. Needs integrations:write: the rows can be anything the
        warehouse login can read.
      operationId: integrations_run_sql
      parameters:
        - description: The integration key, such as snowflake or salesforce
          in: path
          name: key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                end_date:
                  anyOf:
                    - format: date
                      type: string
                    - type: 'null'
                  default: null
                  description: Fills {END_DATE} instead of a period, with start_date
                  title: End Date
                limit:
                  default: 100
                  description: The most rows to return
                  maximum: 1000
                  minimum: 1
                  title: Limit
                  type: integer
                period:
                  anyOf:
                    - enum:
                        - HOURLY
                        - TWO_HOURS
                        - FOUR_HOURS
                        - SIX_HOURS
                        - TWELVE_HOURS
                        - DAILY
                        - WEEKLY
                        - MONTHLY
                      type: string
                    - type: 'null'
                  default: null
                  description: >-
                    Fills the date placeholders with the latest complete period;
                    weekly when left out
                  title: Period
                sql:
                  description: >-
                    One SELECT, in the warehouse's own dialect. It may use
                    {START_DATE}, {END_DATE}, {START_DATE_SQL} and
                    {END_DATE_SQL}, which each run fills with its period's dates
                  maxLength: 100000
                  minLength: 1
                  title: Sql
                  type: string
                start_date:
                  anyOf:
                    - format: date
                      type: string
                    - type: 'null'
                  default: null
                  description: Fills {START_DATE} instead of a period, with end_date
                  title: Start Date
              required:
                - sql
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationSqlRows'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    IntegrationSqlRows:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/IntegrationSqlColumn'
          title: Columns
          type: array
        duration_ms:
          title: Duration Ms
          type: integer
        row_count:
          title: Row Count
          type: integer
        rows:
          description: >-
            As JSON: decimals a float would round as strings, times ISO-8601,
            bytes base64
          items:
            additionalProperties: true
            type: object
          title: Rows
          type: array
        tables_referenced:
          items:
            type: string
          title: Tables Referenced
          type: array
        truncated:
          description: More rows matched than `limit`
          title: Truncated
          type: boolean
        window_end:
          description: What {END_DATE} was filled with
          format: date-time
          title: Window End
          type: string
        window_start:
          description: What {START_DATE} was filled with
          format: date-time
          title: Window Start
          type: string
      required:
        - columns
        - rows
        - row_count
        - truncated
        - duration_ms
        - tables_referenced
        - window_start
        - window_end
      title: IntegrationSqlRows
      type: object
    IntegrationSqlColumn:
      properties:
        name:
          title: Name
          type: string
        type:
          description: >-
            number, text, boolean, date, datetime, time, bytes, json or empty:
            read from the values
          title: Type
          type: string
      required:
        - name
        - type
      title: IntegrationSqlColumn
      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.