---
title: "Execute a TRQL query"
method: POST
path: "/api/v1/query"
tags: ["query"]
---

# Execute a TRQL query

`POST /api/v1/query`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v1/query`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v1/query/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Request body

- ExecuteQueryRequestBody
  - `query` string, required: The TRQL query to execute
  - `scope` 'environment' | 'project' | 'organization': The scope of data to query - environment (default), project, or organization
  - `period` string, nullable: Time period shorthand (e.g., "7d", "30d", "1h"). Cannot be used with from/to.
  - `from` string, date-time, nullable: Start of time range as ISO 8601 timestamp. Must be used with 'to'.
  - `to` string, date-time, nullable: End of time range as ISO 8601 timestamp. Must be used with 'from'.
  - `format` 'json' | 'csv': Response format - "json" returns structured data (default), "csv" returns CSV string

## Response `200`

Query executed successfully

- union
  - object: JSON format response
    - `format` 'json'
    - `results` object[]: Array of result rows
  - object: CSV format response
    - `format` 'csv'
    - `results` string: CSV-formatted results

## Other responses

- `400`: Invalid query or request parameters
- `401`: Unauthorized - API key is missing or invalid
- `429`: Query service is busy or rate limited - retry shortly
- `500`: Internal server error during query execution

## Changes

- **2026-08-12** `5a7281dd54f7`: 1 info
  - added the non-success response with the status `429`
- **2026-02-19** `139dd7987c6d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/query/post.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)