# POST /reports/query

**Resource:** [Reports](./reports.md)  
**Scopes:** `opportunities:read`  
**Write operation:** no

Run a report query. Returns aggregated rows for charts, or individual rows for drilldowns. Sources: "deals" (pipeline performance, revenue, win/loss) and "tasks" (open/overdue/by-assignee). In drilldown mode, the dimensions[] array controls which columns are returned and in what order (up to 8 columns via display_config.columns on a saved card).

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `source` | body | string | yes | Data source: "deals" or "tasks". |
| `measures` | body | array | no | Array of { field, aggregation, alias }. deals fields: id (count), value, products_total_value, product_count. tasks fields: id (count). Aggregations: count, sum, avg, min, max. |
| `dimensions` | body | array | no | In aggregate mode: group-by fields. In drilldown mode: also sets which columns are returned in order. deals fields: status, pipeline_name, stage_name, assigned_user_name, lead_source, currency, won_reasons, lost_reasons, product_names, product_categories. tasks fields: status, priority, category, assignee_name, deal_name, contact_name, is_overdue, client (virtual -- display only, resolves to contact_name falling back to deal_name; cannot be filtered or sorted). Virtual dimensions (virtual:true in /reports/sources) are computed in JS post-fetch and cannot appear in filters or order_by. |
| `filters` | body | array | no | Array of { field, operator, value/values }. Operators: eq, neq, gt, gte, lt, lte, in, not_in, like, is_null, is_not_null, contains. Do not filter on virtual dimensions. |
| `time_dimension` | body | object | no | { field, granularity }. deals: field is deal_created_at, won_at, lost_at, placed_at. tasks: field is due_date, task_created_at, completed_at. granularity: day, week, month, quarter, year. |
| `mode` | body | string | no | "aggregate" (default) returns grouped/summed rows. "drilldown" returns individual rows from the source; dimensions[] controls which columns are returned. |
| `order_by` | body | array | no | Sort order. Array of { field, direction } objects where direction is "asc" or "desc". Can also be a single { field, direction } object. "sort" is accepted as an alias. Cannot sort on virtual dimensions. |
| `drilldown_dimension` | body | string | no | For drilldown mode: dimension field to filter by. |
| `drilldown_value` | body | string | no | For drilldown mode: value to match on drilldown_dimension. |
| `limit` | body | number | no | Max rows (default 100, max 1000). |

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`