> ## Documentation Index > Fetch the complete documentation index at: https://juo.dev/llms.txt > Use this file to discover all available pages before exploring further. # Query analytics > Executes a time-series analytics query for a given metric. ## OpenAPI ````yaml openapi-admin.json POST /analytics/query openapi: 3.1.0 info: title: Juo Admin API version: 1.0.0 description: >- Programmatic access to subscription management for merchants. ## Core Resources - **Subscriptions** — the central entity. Belongs to a Customer, contains Items (product variants) and Discounts. Lifecycle: `active` → `paused` or `cancelled`; `paused` → `active` or `cancelled`; `cancelled` → `active` (via reactivate). - **Items** — subscription items (product variants) (quantity, price, billing/delivery policies). - **Discounts** — applied to subscriptions by discount code or manually (percentage or fixed amount, targeting subscription items or shipping). - **Customers** — customers who own subscriptions and payment methods. - **Products / Variants** — catalog products and variants that can be assigned to subscription plans. - **Schedules** — a read-only projection of upcoming billing orders, derived from subscription state, active schedule adjustments, and triggered workflows. **Schedule adjustments never modify the subscription** — they apply changes to upcoming orders matching the specified criteria (by cycle, date, or both), which may cover one or more orders. For permanent changes (billing frequency, items, payment method, delivery address), update the subscription directly. - **Workflows** — interactive customer-facing flows (retention, dunning, onboarding). Contain Steps connected by Transitions and produce Runs on each execution. Supports A/B experiment steps. ## Authentication Every request requires: - `X-Juo-Admin-Api-Key` header — the merchant's Admin API key. - `X-Tenant-ID` header — the store identifier (myshopify domain, e.g. `my-store.myshopify.com`). servers: - url: https://api.juo.io/admin/v1 security: - AdminApiKey: [] - BearerToken: [] tags: - name: subscriptions description: >- Recurring billing agreements with customers. Manage lifecycle (pause, resume, cancel, reactivate), items, and discounts. - name: customers description: Customers who own subscriptions. Create and update customer records. - name: products description: >- Products and variants linked to subscription plans. Manage catalog and plan assignments. - name: schedules description: >- Read-only view of upcoming billing orders generated from subscription state, schedule adjustments, and workflows. Use schedule adjustments for targeted changes to upcoming orders (scoped by cycle number, date, or both) — they never alter the subscription itself. For permanent changes (billing frequency, items, payment method), update the subscription directly. - name: workflows description: >- Interactive customer-facing flows for retention, dunning, and onboarding. Define steps, publish, and track execution runs and experiments. - name: analytics description: >- Time-series metrics over subscriptions, customers and orders. Read the metric catalog first: it states what each metric means, the approximations it carries, and which filters and group-by dimensions the metric will honour — an unsupported filter is a 400, not an empty result. paths: /analytics/query: post: tags: - analytics summary: Query analytics metrics description: >- Executes a time-series analytics query for the given metric. Results are grouped into time buckets of the requested granularity and, optionally, by additional dimensions. Supports filtering via the segment IR, currency conversion for monetary metrics, and cohort analysis. parameters: - $ref: '#/components/parameters/TenantHeader' requestBody: content: application/json: schema: type: object properties: metric: description: >- The metric to compute, e.g. `subscriptions:mrr`, `customers:count`, `subscriptions:purchased`. type: string enum: - customers:count - customers:status-changes - customers:churned - subscriptions:count - subscriptions:purchased - subscriptions:renewed - subscriptions:canceled - order-items:revenue - subscriptions:cancellation-flow - customers:ltv - orders:lifetime-aov - customers:avg-lifetime-orders - subscriptions:churned - subscriptions:unique-churned - subscriptions:churned-mrr - orders:with-items - orders:item-aov - subscriptions:mrr - customers:revenue-per-customer - orders:count - orders:revenue - orders:aov - order-items:count - order-items:units - orders:avg-units - customers:new - customers:reactivations - customers:resumes - customers:pauses - customers:churn-transitions - subscriptions:status-changes - subscriptions:pauses - subscriptions:current-mrr - subscription-items:count dimensions: description: >- Optional list of dimension keys to group results by, e.g. `["plan_id", "billing_interval"]`. type: array items: type: string filter: $ref: '#/components/schemas/SegmentNode' grain: description: Time bucket granularity used to group results. type: string enum: - day - week - month - year - total range: type: object properties: from: minLength: 1 description: >- Start of the date range (ISO 8601 date string, inclusive). type: string to: minLength: 1 description: End of the date range (ISO 8601 date string, inclusive). type: string required: - from - to timezone: description: >- IANA timezone name used to align bucket boundaries, e.g. `America/New_York`. Defaults to UTC. type: string currency: description: >- ISO 4217 currency code to convert monetary metrics to, e.g. `USD`. When omitted, values are returned in the tenant's default currency. type: string cohort: description: >- Optional cohort definition. When present, returns a retention triangle or LTV-by-cohort matrix. type: object properties: anchorEvent: description: The anchor event type, e.g. 'subscription:purchased'. type: string periodGrain: description: Time grain for cohort periods. type: string enum: - day - week - month - year measure: description: >- Cohort measure: 'retention' (survival) or 'ltv' (cumulative LTV per subscriber). type: string enum: - retention - ltv periods: minimum: 1 maximum: 36 description: >- Number of relative periods to compute (0..periods for calendar; 1..periods for order_sequence). Default 12. type: integer periodBasis: description: >- How relative periods are defined. 'calendar' (default): period N = N calendar grains after the anchor. 'order_sequence': period N = billing-order number (1-based; N=1 = initial purchase, N=2 = first renewal, etc.). type: string enum: - calendar - order_sequence required: - anchorEvent - periodGrain - measure rollup: description: >- Aggregation function to apply over time buckets (default: sum). Only applies to metrics that support it. type: string enum: - sum - avg - min - max - last required: - metric - grain - range required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: series: description: Ordered list of time-bucketed data points. type: array items: type: object properties: start: description: >- Inclusive start of the time bucket as an ISO 8601 datetime string. type: string end: description: >- Inclusive end of the time bucket as an ISO 8601 datetime string. type: string dimensions: description: >- Dimension key-value pairs for this data point, matching the requested `dimensions` array. type: object additionalProperties: {} value: description: >- Computed metric value for this bucket and dimension combination. type: number required: - start - end - dimensions - value meta: type: object properties: additivity: description: >- Additivity class of the metric: `additive`, `semi-additive`, or `non-additive`. Determines whether values can be summed across time or dimensions. type: string sourceModel: description: >- Internal identifier of the data model used to compute the metric. type: string currencyConverted: description: >- Whether monetary values were converted to the requested currency. type: boolean unit: description: >- Unit of the metric value: 'money_minor' means the raw value is in minor currency units (÷100 = major units). Absent for dimensionless counts. type: string ignoredFilters: description: >- Filter fields that could not be applied to this metric's source model; the returned values are NOT filtered by them. type: array items: type: string required: - additivity - sourceModel - currencyConverted required: - series - meta '400': description: >- Bad request — invalid input or violated business rule (e.g., wrong subscription status for the requested operation). '401': description: Unauthorized — missing, expired, or invalid API key. '403': description: Forbidden — authenticated but not permitted to access this resource. '404': description: >- Not found — the resource does not exist or belongs to a different tenant. '422': description: >- Unprocessable entity — well-formed request that fails semantic validation. components: parameters: TenantHeader: name: X-Tenant-ID x-speakeasy-name-override: tenant x-speakeasy-globals-hidden: true in: header schema: type: string required: true description: >- Unique identifier of the tenant in the system (usually a store identifier) schemas: SegmentNode: anyOf: - type: object properties: op: type: string enum: - AND - OR children: type: array items: $ref: '#/components/schemas/SegmentNode' required: - op - children - type: object properties: field: description: >- Dimension key to filter on. Must be a registered analytics dimension. type: string enum: - event.status_from - event.status_to - event.event_type - event.amount - event.currency - order_item.is_first_order - order_item.is_subscription - event.is_build_a_box - event.is_upsell - event.customer_id - event.subscription_id - event.order_id - event.product_id - event.variant_id - event.cycle_index - event.billing_interval - event.actor_id - event.actor_type - event.owner_id - order_item.selling_plan_id - event.subscription_item_id - subscription.has_item_with_plan_id - subscription.has_item_with_plan_name - subscription_item.is_recurring - subscription_item.is_virtual - subscription.current_status - subscription.amount_per_cycle - subscription.current_billing_interval - subscription.billing_interval_count - subscription.has_renewed - subscription.renewal_count - subscription.first_purchase_at - props.reason - props.action operator: type: string enum: - eq - ne - gt - gte - lt - lte - in - nin - is_null - is_not_null value: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean required: - field - operator title: SegmentNode securitySchemes: AdminApiKey: type: apiKey name: X-Juo-Admin-Api-Key in: header description: >- Long-lived Admin API key issued from the Juo merchant portal. Pass as the `X-Juo-Admin-Api-Key` header. BearerToken: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT minted via the merchant browser-session flow. Carries the authenticated staff identity so that API calls are attributed to the specific staff user in the activity log. ````