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.

POST /api/v1/query

TypeScript

SDK - Basic query

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);

200

{
  "format": "json",
  "results": [
    {}
  ]
}

See the Query documentation for comprehensive examples including:

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

Authorizations

Authorization · string · header · required

Use your project-specific Secret API key. Will start with tr_dev_, tr_prod, tr_stg, etc.

You can find your Secret API key in the API Keys section of your Trigger.dev project dashboard.

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.

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

configure({ accessToken: "tr_dev_1234" });

Body

application/json

query · string · required

The TRQL query to execute

Example:

"SELECT run_id, status, triggered_at FROM runs WHERE status = 'Failed' LIMIT 10"

scope · enum<string> · default: environment

The scope of data to query - environment (default), project, or organization

Available options: environment, project, organization

period · string | null

Time period shorthand (e.g., "7d", "30d", "1h"). Cannot be used with from/to.

Example:

"7d"

from · string<date-time> | null

Start of time range as ISO 8601 timestamp. Must be used with 'to'.

Example:

"2024-01-01T00:00:00Z"

to · string<date-time> | null

End of time range as ISO 8601 timestamp. Must be used with 'from'.

Example:

"2024-01-31T23:59:59Z"

format · enum<string> · default: json

Response format - "json" returns structured data (default), "csv" returns CSV string

Available options: json, csv

Response

200

application/json

Query executed successfully

Option 1

Option 2

JSON format response

format · enum<string>

Available options: json

results · object[]

Array of result rows