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

# Execute a TRQL query

`POST /api/v1/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.

## 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
- `500` — Internal server error during query execution

---

[API](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api.md) · [All operations](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/winsenlabs/trigger-dev-v3-rest-api/revisions/737c498e605b/schema)