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

# Execute a query

> Execute a TRQL (Trigger.dev Query Language) query against your run data. TRQL is a SQL-style query language that allows you to analyze runs, calculate metrics, and export data.

See the [Query documentation](https://trigger.dev/docs/observability/query.md#example-queries) for comprehensive examples including:

* Failed runs analysis
* Task success rates over time
* Cost tracking and optimization
* Performance metrics and percentiles


## OpenAPI

````yaml v3-openapi POST /api/v1/query
openapi: 3.1.0
info:
  title: Trigger.dev v3 REST API
  description: >-
    The REST API lets you trigger and manage runs on Trigger.dev. You can
    trigger a run, get the status of a run, and get the results of a run. 
  version: 2024-04
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://api.trigger.dev
    description: Trigger.dev API
security: []
paths:
  /api/v1/query:
    post:
      tags:
        - query
      summary: Execute a TRQL query
      description: >-
        Execute a TRQL (Trigger.dev Query Language) query against your run data.
        TRQL is a SQL-style query language that allows you to analyze runs,
        calculate metrics, and export data.
      operationId: execute_query_v1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteQueryRequestBody'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteQueryResponse'
        '400':
          description: Invalid query or request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message describing the query error
        '401':
          description: Unauthorized - API key is missing or invalid
        '429':
          description: Query service is busy or rate limited - retry shortly
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message describing why the query was turned away
        '500':
          description: Internal server error during query execution
      security:
        - secretKey: []
      x-codeSamples:
        - lang: typescript
          label: SDK - Basic query
          source: |-
            import { query } from "@trigger.dev/sdk";

            // Basic query with defaults (environment scope, json format)
            const result = await query.execute(
              "SELECT run_id, status FROM runs LIMIT 10"
            );
            console.log(result.results);
        - lang: typescript
          label: SDK - Type-safe query
          source: |-
            import { query, type QueryTable } from "@trigger.dev/sdk";

            // Type-safe query using QueryTable
            const result = await query.execute<
              QueryTable<"runs", "run_id" | "status" | "triggered_at">
            >(
              "SELECT run_id, status, triggered_at FROM runs LIMIT 10"
            );

            result.results.forEach(row => {
              console.log(row.run_id, row.status); // Fully typed!
            });
        - lang: typescript
          label: SDK - With options
          source: |-
            import { query } from "@trigger.dev/sdk";

            const result = await query.execute(
              "SELECT COUNT(*) as count FROM runs WHERE status = 'Failed'",
              {
                scope: "project",       // Query across all environments
                period: "7d",           // Last 7 days
                format: "json"
              }
            );
        - lang: typescript
          label: SDK - CSV export
          source: |-
            import { query } from "@trigger.dev/sdk";

            const csvResult = await query.execute(
              "SELECT run_id, status, triggered_at FROM runs",
              {
                format: "csv",
                period: "30d"
              }
            );

            // csvResult.results is a CSV string
            const lines = csvResult.results.split('\n');
        - lang: curl
          label: cURL - Basic query
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/query" \
              -H "Authorization: Bearer tr_dev_sk_1234" \
              -H "Content-Type: application/json" \
              -d '{
                "query": "SELECT run_id, status FROM runs LIMIT 10",
                "scope": "environment",
                "period": "7d",
                "format": "json"
              }'
        - lang: curl
          label: cURL - Aggregation query
          source: |-
            curl -X POST "https://api.trigger.dev/api/v1/query" \
              -H "Authorization: Bearer tr_dev_sk_1234" \
              -H "Content-Type: application/json" \
              -d '{
                "query": "SELECT task_identifier, count() as runs, countIf(status = '\''Failed'\'') as failures FROM runs GROUP BY task_identifier",
                "scope": "environment",
                "from": "2024-01-01T00:00:00Z",
                "to": "2024-01-31T23:59:59Z",
                "format": "json"
              }'
components:
  schemas:
    ExecuteQueryRequestBody:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: The TRQL query to execute
          example: >-
            SELECT run_id, status, triggered_at FROM runs WHERE status =
            'Failed' LIMIT 10
        scope:
          type: string
          enum:
            - environment
            - project
            - organization
          default: environment
          description: >-
            The scope of data to query - environment (default), project, or
            organization
        period:
          type: string
          nullable: true
          description: >-
            Time period shorthand (e.g., "7d", "30d", "1h"). Cannot be used with
            from/to.
          example: 7d
        from:
          type: string
          format: date-time
          nullable: true
          description: Start of time range as ISO 8601 timestamp. Must be used with 'to'.
          example: '2024-01-01T00:00:00Z'
        to:
          type: string
          format: date-time
          nullable: true
          description: End of time range as ISO 8601 timestamp. Must be used with 'from'.
          example: '2024-01-31T23:59:59Z'
        format:
          type: string
          enum:
            - json
            - csv
          default: json
          description: >-
            Response format - "json" returns structured data (default), "csv"
            returns CSV string
    ExecuteQueryResponse:
      oneOf:
        - type: object
          description: JSON format response
          properties:
            format:
              type: string
              enum:
                - json
            results:
              type: array
              items:
                type: object
              description: Array of result rows
        - type: object
          description: CSV format response
          properties:
            format:
              type: string
              enum:
                - csv
            results:
              type: string
              description: CSV-formatted results
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      description: >
        Use a named environment API key. It starts with `tr_dev_sk_`,
        `tr_prod_sk_`, `tr_stg_sk_`, etc.


        Create a named API key in the API Keys section of your Trigger.dev
        project dashboard. Choose the narrowest access preset that supports your
        integration.


        Our TypeScript SDK will default to using the value of the
        `TRIGGER_SECRET_KEY` environment variable if it is set. If you are using
        the SDK in a different environment, you can set the key using the
        `configure` function.


        ```typescript

        import { configure } from "@trigger.dev/sdk";


        configure({ accessToken: "tr_dev_sk_1234" });

        ```

````

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