> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt > Use this file to discover all available pages before exploring further. # Report > Aggregate cost data across costs and customers with grouping, filtering, and time-series breakdown. ## OpenAPI ````yaml /openapi.json get /v0/costs/report openapi: 3.1.0 info: title: Paygentic API version: 0.1.0 description: > The Paygentic API provides a comprehensive platform for building and scaling monetization infrastructure. ## Authentication All API requests require authentication using an API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL All API requests should be made to: ``` https://api.paygentic.io/v0 ``` contact: name: Paygentic Support email: support@paygentic.io license: name: Proprietary servers: - url: https://api.paygentic.io description: Production API - url: https://api.sandbox.paygentic.io description: Sandbox API security: - BearerAuth: [] tags: - name: Customers description: >- A `Customer` is an entity connected to a `Merchant` via a `Subscription`. This represents the merchant-facing perspective of `Consumers` who purchase their `Products`. - name: Billable Metrics description: >- A `Billable Metric` defines a measurable quantity tied to a `Product`'s consumption. Each metric stores details including its label, an explanatory description, and measurement units. - name: Grants description: >- Grants credit a customer's metered entitlement balance. Merchants can create grants directly or void existing ones. Use `GET /v1/entitlements?customerId={id}` or `GET /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id` needed for these endpoints. - name: Features description: >- A `Feature` represents a specific capability or functionality provided by a `Product`. Features can be metered (usage-based), static (fixed allocation), or boolean (enabled/disabled). - name: Fees description: >- A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees are linked to prices, and cadence is defined on the Price. - name: Plans description: >- A `Plan` links a collection of `Prices` to a `Product`. It functions as a pricing structure document for a particular feature set or service offering. - name: Prices description: >- A `Price` determines the monetary value for a single unit of a `Billable Metric`. Prices are exclusively grouped within a `Plan`. - name: Products description: >- A `Product` is an offering sold by a `Merchant`. It includes product metadata like title, summary, and pricing details. `Plans`, `Prices`, and `Subscriptions` are all associated with products. - name: Sources description: >- A `Source` is an external data provider capable of automatically creating usage events. Configuration occurs at the plan level, enabling data retrieval from third-party platforms such as Stripe to produce billable events. - name: Subscriptions description: >- A `Subscription` is a customer's commitment to purchase a `Product` following the terms of a `Plan` and its linked `Prices`. - name: Users description: >- A `User` is an entity granted access to an Organization's resources. All operations are performed by users. - name: Invoices V2 description: >- Invoice V2 operations supporting billing cycles organized by time periods. Warning: v0 invoice endpoints are no longer supported. - name: Revenue description: Revenue data from invoices and payments - name: Profitability description: Per-customer profitability summaries - name: Test Clocks description: >- Test clocks provide programmable time control to simulate subscription and billing scenarios during testing. - name: Events description: Ingest raw metering events that are processed by the meters service. - name: Payments description: >- Create and manage one-off payments. A payment represents a single charge that a merchant wants to collect from a customer. - name: Payment Sessions description: >- Handle payment session lifecycle and processing across various entity types including invoices and subscriptions - name: Costs description: >- A Cost represents the operational or infrastructure expense of serving customers for a given product. Costs are metered (driven by event-based usage) and are tracked in parallel with billable metrics to give merchants visibility into both revenue and cost per customer. - name: ExternalReferences description: >- An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a record in an external system such as Salesforce or NetSuite. Multiple external records may map to the same Paygentic entity, but each external id is the *primary* reference of at most one entity per merchant. - name: Items description: >- An `Item` is the canonical "thing you sell" that external-system mappings point at. It is fully decoupled from the billing `Product` and holds no pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to it lives entirely in its `ExternalReference` rows. - name: MerchantIntegrations description: >- A `MerchantIntegration` records a merchant's connection to an external provider. One connection per `(merchant, provider)` — re-connecting upserts in place. - name: Approvals description: Submit, decide, cancel, and read maker-checker approvals. - name: Orders description: Manage Orders, their line items, and billing schedules. - name: Billing Schedules description: >- Owner-polymorphic billing schedules with intervals and staged invoice projections. A BillingSchedule belongs to exactly one Order or one Subscription (XOR). Cadence lives on ScheduleIntervals (cadence-on-the-line). paths: /v0/costs/report: get: tags: - Costs summary: Report description: >- Aggregate cost data across costs and customers with grouping, filtering, and time-series breakdown. operationId: getCostReport parameters: - name: merchantId in: query required: false schema: type: string description: >- The merchant organization ID. If omitted, defaults to the merchant associated with the authenticated API key. - name: from in: query required: true schema: type: string format: date-time description: Start of the query window (ISO 8601). - name: to in: query required: true schema: type: string format: date-time description: End of the query window (ISO 8601). - name: groupBy in: query required: true schema: type: string description: >- Dimension to group results by. Valid values: 'cost' (group by cost ID), 'customer' (group by customer ID), or any dimension key from a filtered cost's groupBy schema for dynamic dimension grouping. Dynamic dimension values require exactly one costId filter. examples: byCost: value: cost byCustomer: value: customer byDimension: value: region - name: costId in: query required: false style: form explode: true schema: type: array items: type: string description: Filter to specific cost(s). Enables dynamic dimension grouping. - name: subject in: query required: false schema: type: string description: Filter to a specific subject (customer/event subject ID). - name: filterGroupBy in: query required: false schema: type: string maxLength: 4096 description: >- JSON-encoded dimension filters (e.g. {"region":"us-east-1"}). Max 4KB, max 5 keys. - name: topN in: query required: false schema: type: integer minimum: 1 maximum: 25 default: 9 description: >- Number of top groups to return. An 'Other' bucket aggregates remaining groups. - name: comparePriorPeriod in: query required: false schema: type: boolean default: false description: When true, include prior-period comparison data in each group. - name: windowSize in: query required: false schema: type: string enum: - HOUR - DAY - MONTH description: Time window granularity for the time-series breakdown. - name: sort in: query required: false schema: type: string enum: - totalCost - totalQuantity default: totalCost description: Field to sort groups by. - name: sortDir in: query required: false schema: type: string enum: - asc - desc default: desc description: Sort direction. - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: Number of groups to skip for pagination. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 25 description: Maximum number of groups to return. - name: currency in: query required: false schema: type: string description: >- Filter costs to a single ISO 4217 currency code (e.g. 'USD'). When omitted, defaults to the merchant's primary currency. responses: '200': description: Aggregated cost report content: application/json: schema: $ref: '#/components/schemas/CostReportResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CostReportResponse: type: object required: - object - currency - period - groupBy - totalCost - totalQuantity - groups - timeSeries - availableDimensions - pagination properties: object: type: string enum: - cost_report default: cost_report currency: type: string description: ISO 4217 currency code for all monetary values in this response. period: type: object required: - from - to properties: from: type: string format: date-time to: type: string format: date-time groupBy: type: string description: >- The active grouping dimension (e.g. 'cost', 'customer', or a dynamic dimension key). totalCost: type: number description: Sum of cost across all groups (not just top N). totalQuantity: type: number description: Sum of quantity across all groups. groups: type: array items: $ref: '#/components/schemas/CostReportGroup' description: Top N groups plus an 'Other' bucket aggregating the remainder. timeSeries: type: array items: $ref: '#/components/schemas/CostReportTimeSeries' description: >- Time-bucketed breakdown per group. Keys in each window's 'groups' object correspond to CostReportGroup.key. The 'Other' bucket key is '__other__'. availableDimensions: type: array items: type: string description: >- Dimension keys available for further drill-down (populated when a single cost is filtered). warnings: type: array items: type: string description: Non-fatal warnings, e.g. costs that could not be queried. pagination: type: object required: - total - limit - offset properties: total: type: integer limit: type: integer offset: type: integer CostReportGroup: type: object required: - key - label - totalCost - totalQuantity - percentOfTotal - isOther properties: key: type: string description: >- Group identifier (cost ID, customer ID, or dimension value). '__other__' for the aggregated remainder bucket. label: type: string description: Human-readable display name for the group. totalCost: type: number totalQuantity: type: number unit: type: string nullable: true description: Unit label for the quantity (e.g. 'token', 'request'). percentOfTotal: type: number description: This group's share of total cost, 0–100. priorPeriod: type: object nullable: true required: - cost - changePercent properties: cost: type: number changePercent: type: - number - 'null' description: >- Percentage change vs prior period. Null when prior period cost is 0. description: >- Prior-period comparison data. Present only when comparePriorPeriod=true. isOther: type: boolean description: True for the aggregated 'Other' bucket. CostReportTimeSeries: type: object required: - windowStart - windowEnd - groups properties: windowStart: type: string format: date-time windowEnd: type: string format: date-time groups: type: object additionalProperties: type: number description: >- Map of group key → cost value for this time window. Keys match CostReportGroup.key. Error: type: object required: - message properties: error: type: string description: >- Coarse HTTP error category (e.g. 'bad_request', 'forbidden'). Maps to the HTTP status code. message: type: string description: >- Human-readable error message. Clients must not parse this field programmatically. code: type: string examples: - TAX_NOT_ENABLED - PAYMENT_SESSION_EXPIRED description: >- Optional semantic business error code for machine-readable discrimination (e.g. 'TAX_NOT_ENABLED'). UPPER_SNAKE_CASE. Clients should check this field, not message. details: type: object description: Additional error details additionalProperties: true example: message: The requested resource was not found error: not_found ValidationError: type: object required: - message - errors properties: error: type: string enum: - validation_error default: validation_error description: Error type indicating validation failure message: type: string description: Human-readable error message errors: type: array items: type: object properties: field: type: string description: The field that failed validation message: type: string description: Validation error message for this field code: type: string description: Validation error code required: - field - message description: Array of field-specific validation errors example: message: Validation failed error: validation_error errors: - field: email message: Invalid email format code: invalid_format responses: BadRequest: description: >- Bad Request - The request could not be understood or was missing required parameters content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Unauthorized: description: Unauthorized - Authentication failed or user does not have permissions content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden - Request is understood but refused content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - Something went wrong on the server side content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer description: API key authentication ````