---
title: "Return timeseries data from arbitrary queries"
method: POST
path: "/v1/org/{orgId}/report/query"
tags: ["report"]
---

# Return timeseries data from arbitrary queries

`POST /v1/org/{orgId}/report/query`

## Path parameters

- `orgId` string, required

## Request body

- ReportQuery
  - `series` ReportSeriesQuery[] — series to evaluate
    - `label` string, required — label to use
    - `color` string, required — color to use
    - `y` string, required — y-value to calculate
    - `groupByConfigs` GroupByConfig[] — Configuration for aggregations performed by the groupBy operator
      - `overrides` LabelOverride[] — Overrides by label of label, color, or sort order
        - `id` string, required — The unique identifier to use to locate the key to override. For entities and enum values, this will be an id. For numbers, this will be the normalized numeric representation. For others, this will be the string
        - `label` string — If set, overrides this label
        - `color` string — If set, overrides the default color
        - `sort` integer — If set, overrides the sorting order
      - `limit` integer — Maximum number of results to display
      - `includeOther` boolean — When combined with limit, whether to include an 'Other' group
      - `includeNone` boolean — Whether to include a 'None' group (null values aggregated)
      - `includeAllValues` boolean — When combined with fieldId or questionId, will include all values from that fieldId or questionId, even if none of them were used
      - `fieldId` string — The field to use to retrieve values, when includeAllValues is in use
      - `questionId` string — The question to use to retrieve values, when includeAllValues is in use
      - `sortBy` 'LABEL' | 'KEY' | 'VALUE' | 'COUNT' — Whether to sort the results -- by default, will sort by label if there is no limit, will sort by value descending if there is a limit
      - `sortDirection` 'ASC' | 'DESC' — The direction to sort the results
  - `filters` ReportFilter[] — filters to crosstab all results by (deprecated in reports V2, should use groupBy instead)
    - `label` string, required — human-readable label for the filter
    - `filter` string, required — filter expression
  - `content` string — content block to evaluate as a Carrot Template, as an alternative to using series
  - `startDate` string — start date, in either relative (-7d) or exact (YYYY-MM-DD) format
  - `endDate` string — end date, in either relative (-7d) or exact (YYYY-MM-DD) format; if not present, defaults to today
  - `interval` 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'FISCAL_QUARTER' | 'YEAR' | 'FISCAL_YEAR' — interval, if the query is a timeseries; if no interval, query is crosstabbed
  - `intervalDates` string[] — interval dates, if a specific set of irregular dates are being queried in a timeseries
  - `options` object, required — options, including format, filter, scenarioId, projectHires, and numerous display options

## Response `200`

successful operation

- ReportResult[]
  - `id` string, required — globally unique id
  - `orgId` string, required — parent org id
  - `key` string, required — identifying key for this report result
  - `startDate` string, date, required — date that the report result interval begins, inclusive
  - `endDate` string, date, required — date that the report result interval ends, exclusive
  - `options` object, required — options that were used for the query
  - `queries` ReportQuery[], required — list of queries that were requested
    - `series` ReportSeriesQuery[] — series to evaluate
      - `label` string, required — label to use
      - `color` string, required — color to use
      - `y` string, required — y-value to calculate
      - `groupByConfigs` GroupByConfig[] — Configuration for aggregations performed by the groupBy operator
        - `overrides` LabelOverride[] — Overrides by label of label, color, or sort order
          - `id` string, required — The unique identifier to use to locate the key to override. For entities and enum values, this will be an id. For numbers, this will be the normalized numeric representation. For others, this will be the string
          - `label` string — If set, overrides this label
          - `color` string — If set, overrides the default color
          - `sort` integer — If set, overrides the sorting order
        - `limit` integer — Maximum number of results to display
        - `includeOther` boolean — When combined with limit, whether to include an 'Other' group
        - `includeNone` boolean — Whether to include a 'None' group (null values aggregated)
        - `includeAllValues` boolean — When combined with fieldId or questionId, will include all values from that fieldId or questionId, even if none of them were used
        - `fieldId` string — The field to use to retrieve values, when includeAllValues is in use
        - `questionId` string — The question to use to retrieve values, when includeAllValues is in use
        - `sortBy` 'LABEL' | 'KEY' | 'VALUE' | 'COUNT' — Whether to sort the results -- by default, will sort by label if there is no limit, will sort by value descending if there is a limit
        - `sortDirection` 'ASC' | 'DESC' — The direction to sort the results
    - `filters` ReportFilter[] — filters to crosstab all results by (deprecated in reports V2, should use groupBy instead)
      - `label` string, required — human-readable label for the filter
      - `filter` string, required — filter expression
    - `content` string — content block to evaluate as a Carrot Template, as an alternative to using series
    - `startDate` string — start date, in either relative (-7d) or exact (YYYY-MM-DD) format
    - `endDate` string — end date, in either relative (-7d) or exact (YYYY-MM-DD) format; if not present, defaults to today
    - `interval` 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'FISCAL_QUARTER' | 'YEAR' | 'FISCAL_YEAR' — interval, if the query is a timeseries; if no interval, query is crosstabbed
    - `intervalDates` string[] — interval dates, if a specific set of irregular dates are being queried in a timeseries
    - `options` object, required — options, including format, filter, scenarioId, projectHires, and numerous display options
  - `results` ReportQueryResult[], required — list of the results, one per query that was requested
    - `series` ReportSeriesResult[], required — list of series results
      - `label` string, required — human-readable label for the series
      - `color` string, required — suggested color for the series
      - `format` string, required — number format (currently 'number', 'money', 'percent' allowed)
      - `data` object[], required — array of items in the series
      - `xAxis` LabelColor[] — labels and colors of the values in the X-axis, if the X-axis is not a timeseries
        - `label` string, required — human-readable label for the value
        - `color` string, required — suggested color for the value
      - `isIntervalMetric` boolean, required — true if the metric being returned is reporting on the entire interval (includes the intervalFrom or intervalUntil metric), false if just the last date in the interval
    - `content` string — the results of rendering the content block, if a content template was used in the query
    - `groupBys` ReportGroupByDimension[] — list of group-by dimensions with default values
      - `keys` ReportGroupByKey[], required — list of keys appearing in the groupBy
        - `id` string, required — unique string identifier for this key
        - `color` string, required — color for this key, prior to any overrides
        - `label` string, required — label for this key, prior to any overrides
        - `imagePath` string — S3-relative avatar/icon/logo path for this key (EntityTag form), when resolved server-side
        - `orgId` string — owning org of this key's entity, when the key spans orgs of a customer
    - `dateIntervals` ReportDateInterval[] — list of group-by dimensions with default values
      - `startDate` string, date, required
      - `endDate` string, date, required
      - `partialStartDate` string, date
      - `partialEndDate` string, date
    - `version` integer — version used to generate the results
  - `buildStartAt` string — start time of last build
  - `buildEndAt` string — end time of last build
  - `message` string — status or error message
  - `progress` number, double — percent progress so far
  - `viewId` string — viewer user id
  - `createId` string, required — created by user id
  - `createBehalfId` string — created on behalf of user id
  - `createAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `createAt` string, required — created timestamp
  - `status` 'OK' | 'LOCKED' | 'RETRY' | 'ERROR', required — status of the report result
  - `reportId` string — corresponding report id for the built query
  - `chartId` string — corresponding chart id for the built query

## Other responses

- `400` — bad request
- `401` — not authorized
- `404` — not found

---

[API](https://skmtc.dev/charthop/apis/charthop-api.md) · [All operations](https://skmtc.dev/charthop/apis/charthop-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/charthop/charthop-api/revisions/4685d95a20b1/schema)