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

# Query events in SQL

> Run a read-only ClickHouse SQL query over your usage events and rollups. Scoped to your organization and environment. SETTINGS clauses are not allowed. Streams compressed newline-delimited JSON; see the [events SQL guide](/documentation/query-events-with-sql).

### Body Parameters

Read-only ClickHouse SQL over usage events and rollups, scoped to your organization and environment. SETTINGS clauses are not allowed.

```json 200 theme={null}
{"type":"columns","columns":[{"name":"event_name","type":"String"},{"name":"event_count","type":"UInt64"}]}
{"type":"row","values":["api_call","42"]}
{"type":"row","values":["message_sent","17"]}
{"type":"end","rows":2,"truncated":false,"stopped_by":null}
```

```json 200 with error theme={null}
{"type":"columns","columns":[{"name":"event_name","type":"String"},{"name":"event_count","type":"UInt64"}]}
{"type":"row","values":["api_call","42"]}
{"type":"error","code":"statement_timeout","message":"Query exceeded the 30s compute limit for your plan and was cancelled. Narrow it (filter by date or customer, select fewer columns, or add LIMIT) or contact support@useautumn.com to raise your compute limit.","details":{"limit_ms":30000}}
```


## OpenAPI

````yaml openapi POST /v1/events.query
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.6.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/events.query:
    post:
      tags:
        - events
      summary: Query events in SQL
      description: >-
        Run a read-only ClickHouse SQL query over your usage events and rollups.
        Scoped to your organization and environment. SETTINGS clauses are not
        allowed. Streams compressed newline-delimited JSON; see the [events SQL
        guide](/documentation/query-events-with-sql).
      operationId: queryEvents
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.6.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sql:
                  type: string
                  minLength: 1
                  maxLength: 100000
                  description: >-
                    Read-only ClickHouse SQL over usage events and rollups,
                    scoped to your organization and environment. SETTINGS
                    clauses are not allowed.
              required:
                - sql
              title: EventsQueryParams
              examples:
                - sql: >-
                    SELECT event_name, count() AS event_count FROM events GROUP
                    BY event_name
                - sql: >-
                    SELECT event_name, sum(event_count) AS event_count FROM
                    event_names_mv GROUP BY event_name
            example:
              sql: >-
                SELECT event_name, count() AS event_count FROM events GROUP BY
                event_name
      responses:
        '200':
          description: >-
            A newline-delimited JSON stream. Each line is an
            [AnalyticsQueryLine](#/components/schemas/AnalyticsQueryLine):
            columns first, then one row line per result row, then an end or
            error line.
          content:
            application/x-ndjson:
              schema:
                type: string
                format: binary
              examples:
                success:
                  summary: '200'
                  value: >
                    {"type":"columns","columns":[{"name":"event_name","type":"String"},{"name":"event_count","type":"UInt64"}]}

                    {"type":"row","values":["api_call","42"]}

                    {"type":"row","values":["message_sent","17"]}

                    {"type":"end","rows":2,"truncated":false,"stopped_by":null}
                error:
                  summary: 200 with error
                  value: >
                    {"type":"columns","columns":[{"name":"event_name","type":"String"},{"name":"event_count","type":"UInt64"}]}

                    {"type":"row","values":["api_call","42"]}

                    {"type":"error","code":"statement_timeout","message":"Query
                    exceeded the 30s compute limit for your plan and was
                    cancelled. Narrow it (filter by date or customer, select
                    fewer columns, or add LIMIT) or contact
                    support@useautumn.com to raise your compute
                    limit.","details":{"limit_ms":30000}}
          headers:
            Content-Encoding:
              description: >-
                zstd when the request's Accept-Encoding allows it, otherwise
                gzip.
              schema:
                type: string
                enum:
                  - zstd
                  - gzip
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Autumn } from 'autumn-js'

            const autumn = new Autumn()

            const result = await autumn.events.query({
              sql: "SELECT event_name, count() AS event_count FROM events GROUP BY event_name",
            });
        - lang: python
          label: Python (SDK)
          source: |-
            from autumn_sdk import Autumn

            autumn = Autumn(secret_key="am_sk_test...")

            res = autumn.events.query(
                sql="SELECT event_name, count() AS event_count FROM events GROUP BY event_name",
            )
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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