---
title: "Query Chart Data"
method: POST
path: "/v2/charts/data"
tags: ["Charts V2"]
---

# Query Chart Data

`POST /v2/charts/data`

Queries chart data from ClickHouse based on the provided parameters. Returns time series data with optional breakdowns and filters. Requires charts:read scope.

## Request body

- object
  - `application_id` string, required — Application ID to query data for
  - `y_axis` string, required — Y-axis metric to display (e.g. `netProceeds`, `newUsers`, `trialConversionRate`). Must be an exact metric key from `GET /v2/charts/definitions` — e.g. proceeds charts use `netProceeds`, not `proceeds`.
  - `x_axis` string, required — X-axis dimension (e.g. `purchaseDate`, `installDate`). Must be an exact dimension key from `GET /v2/charts/definitions`.
  - `breakdown` string, nullable — Optional breakdown dimension (e.g. `countryCode`, `placement`)
  - `date_filter` object — Date filter configuration
    - `dimension` 'purchaseDate' | 'installDate' | 'firstPurchaseDate' | 'tsDate' | 'mrrDate', required — Date dimension to filter on
    - `range` object — Custom date range (required when preset is `custom`)
      - `from` string, required — Start date (ISO 8601)
      - `to` string, required — End date (ISO 8601)
    - `preset` 'last_24_hours' | 'today' | 'yesterday' | 'last_7_days' | 'last_30_days' | 'last_90_days' | 'last_180_days' | 'last_365_days' | 'year_to_date' | 'custom' — Preset date range
  - `date_interval` 'auto' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'totals' — Date interval for grouping (hour, day, week, month, quarter, year)
  - `conversion_timeframe` 'd1' | 'd3' | 'd4' | 'd7' | 'd14' | 'd30' | 'd90' — Conversion timeframe for SDK events
  - `include` string[] — Additional y-axis metrics to include in the response
  - `paywall_id` string[] — Filter by paywall IDs
  - `variant_id` string[] — Filter by variant IDs
  - `experiment_id` string[] — Filter by experiment IDs
  - `campaign_id` string[] — Filter by campaign IDs
  - `country_code` string[] — Filter by country codes
  - `product_id` string[] — Filter by product IDs
  - `placement` string[] — Filter by placements
  - `environment` string[] — Filter by environment (SANDBOX, PRODUCTION)
  - `store` string[] — Filter by store (APP_STORE, PLAY_STORE, STRIPE)
  - `app_version` string[] — Filter by app version
  - `sdk_version` string[] — Filter by SDK version
  - `product_duration` string[] — Filter by product duration
  - `billing_plan_type` string[] — Filter by App Store billing plan type (UP_FRONT, MONTHLY)
  - `event_type` string[] — Filter by event type
  - `sub_start_type` string[] — Filter by subscription start type
  - `revenue_type` string[] — Filter by revenue type
  - `auto_renew_status` string[] — Filter by auto renew status
  - `revenue_source` string[] — Filter by revenue source (Superwall, Your App)
  - `max_data_points` number — Maximum number of data points to return (default: 1000)

## Response `200`

Success

- object
  - `object` 'chart_data', required — Object type, always `chart_data`
  - `request_id` string, required — Unique identifier for this request
  - `series` object[], required — List of data series in the response
    - `breakdown` string, required — Breakdown dimension key
    - `key` string, nullable, required — Series key value, or null
  - `data` object[], required — Chart data points
    - `x` string, required — X-axis value (typically a date string)
    - `incomplete` boolean, required — Whether this data point represents an incomplete period
    - `values` object, required — Values keyed by series key
  - `y_axis` object, required — Y-axis definition
    - `key` string, required — Metric key
    - `name` string, required — Display name
    - `description` string, required — Description of the metric
    - `value_type` 'number' | 'percentage' | 'currency', required — How to format the value
    - `extra` object[] — Additional values rendered as sub-rows in chart tables
      - `key` string, required — Metric key
      - `name` string, required — Display name
      - `description` string, required — Description of the metric
      - `value_type` 'number' | 'percentage' | 'currency', required — How to format the value
    - `aggregate_total` object — How to aggregate percentage totals from extra metric values
      - `numerator_key` string, required — Extra metric key to sum for the aggregate total numerator
      - `denominator_key` string, required — Extra metric key to sum for the aggregate total denominator
  - `x_axis` object, required — X-axis definition
    - `key` string, required — Dimension key
    - `name` string, required — Display name
    - `description` string, required — Description of the dimension
    - `value_type` 'date' | 'string', required — Value type of the dimension
    - `fill_missing_values` 'zero' | 'cumulative' — How missing x-axis values are filled
    - `date_intervals` object[] — Supported date interval options for this x-axis
      - `key` 'auto' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'totals', required — Interval key
      - `name` string, required — Display name
      - `description` string, required — Description of the interval
      - `active` boolean
  - `filters` object[], required — Available filters
    - `key` string, required — Filter key
    - `name` string, required — Display name
    - `description` string, required — Description of the filter
    - `active` boolean, required — Whether this filter is currently active
    - `value_type` 'string' | 'date', required — Value type of the filter
    - `value` union[] — Currently selected values
      - union
        - string
        - number
    - `depends_on` string — Filter key that must be selected before this filter is available
  - `breakdowns` object[], required — Available breakdowns
    - `key` string, required — Breakdown key
    - `name` string, required — Display name
    - `description` string, required — Description of the breakdown
    - `active` boolean, required — Whether this breakdown is currently active
    - `value_type` 'string' | 'date', required — Value type of the breakdown
    - `group` string — Group this breakdown belongs to
  - `date_filters` object[], required — Date filter definitions
    - `name` string, required — Display name of the date filter
    - `preset` 'last_24_hours' | 'today' | 'yesterday' | 'last_7_days' | 'last_30_days' | 'last_90_days' | 'last_180_days' | 'last_365_days' | 'year_to_date' | 'custom', required — Active preset
    - `active` boolean, required — Whether this date filter is active
    - `range` object, required — Resolved date range
      - `from` string, required — Start date (ISO 8601)
      - `to` string, required — End date (ISO 8601)
  - `enriched_data` object, required — Enriched metadata for the response
  - `duration` object, required — Request timing information
    - `start_time` number, required — Request start time in milliseconds
    - `end_time` number, required — Request end time in milliseconds
    - `duration_ms` number, required — Total request duration in milliseconds
  - `table` object — Table-specific metadata
    - `kind` 'standard' | 'cohort'
    - `row_meta` object
    - `leading_columns` object[]
      - `key` string, required
      - `label` string, required
      - `value_type` 'number' | 'percentage' | 'currency' | 'string'
      - `align` 'start' | 'end'
      - `sortable` boolean
    - `column_meta` object
    - `hidden_columns` string[]
    - `hidden_series` string[]

## Other responses

- `400` — The request did not match the expected schema
- `401` — No API key was provided in the request
- `403` — The API key does not have permission to perform this action
- `404` — The requested resource was not found
- `429` — Too many requests have been made in a short period
- `500` — An unexpected error occurred on the server

---

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