contentstack Usage Analytics API

openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Usage Analytics API
  description: The Contentstack Analytics API provides access to usage and performance metrics for CMS, Launch, and Automate products within a Contentstack organization. Developers can retrieve analytics data programmatically to build custom dashboards, monitor content delivery performance, and track platform usage against plan limits. The API returns structured data suitable for aggregation with external analytics and business intelligence tools. Access is restricted to organization Owners and Admins. Requests use async job-based processing where initial POST calls queue the job and a subsequent GET call retrieves the results.
  version: v2
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://api.contentstack.io
  description: AWS North America Production Server
- url: https://eu-api.contentstack.com
  description: AWS Europe Production Server
- url: https://au-api.contentstack.com
  description: AWS Australia Production Server
security:
- bearerAuth: []
- authtokenAuth: []
tags:
- name: Usage Analytics
  description: Usage analytics provide bandwidth and API call utilization overviews across Contentstack services including CDN, CMA, Automate, and Launch.
paths:
  /analytics/v2/usage-analytics:
    post:
      operationId: getUsageAnalytics
      summary: Get usage analytics
      description: Provides bandwidth and API call utilization metrics across specified Contentstack services. Useful for monitoring overall platform usage trends and capacity planning.
      tags:
      - Usage Analytics
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageAnalyticsRequest'
      responses:
        '200':
          description: Job queued successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    Forbidden:
      description: The user does not have permission to access analytics. Owner or Admin role required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is malformed or contains invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    AnalyticsRequest:
      type: object
      description: Common parameters for analytics data requests.
      properties:
        from:
          type: string
          format: date
          description: Start date for the analytics query in YYYY-MM-DD format. Maximum range is 90 days.
        to:
          type: string
          format: date
          description: End date for the analytics query in YYYY-MM-DD format.
        duration:
          type: string
          description: Aggregation duration for time series data.
          enum:
          - day
          - week
          - month
        skip:
          type: integer
          description: Number of records to skip for pagination.
          minimum: 0
          default: 0
        limit:
          type: integer
          description: Maximum number of records to return.
          minimum: 1
          maximum: 1000
          default: 100
    JobResponse:
      type: object
      description: Response returned when an analytics job is queued.
      properties:
        jobId:
          type: string
          description: The unique identifier of the queued analytics job. Use this to retrieve results via the GET /analytics/v2/job/{jobId}/data endpoint.
        status:
          type: string
          description: Initial status of the job.
          enum:
          - queued
          - processing
          - completed
          - failed
    Error:
      type: object
      description: Standard error response.
      properties:
        error_message:
          type: string
          description: Human-readable description of the error.
        error_code:
          type: integer
          description: Numeric error code.
    UsageAnalyticsRequest:
      allOf:
      - $ref: '#/components/schemas/AnalyticsRequest'
      - type: object
        properties:
          services:
            type: array
            description: List of Contentstack services to include in the analytics query.
            items:
              type: string
              enum:
              - cdn
              - cma
              - automations
              - launch
          api_key:
            type: string
            description: Optional stack API key to filter metrics to a specific stack.
  parameters:
    OrganizationUid:
      name: organization_uid
      in: header
      required: true
      description: The unique identifier of the organization.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token (M2M) with analytics access.
    authtokenAuth:
      type: apiKey
      in: header
      name: authtoken
      description: Contentstack user authtoken. Only organization Owners and Admins can access analytics.
externalDocs:
  description: Contentstack Analytics API Documentation
  url: https://www.contentstack.com/docs/developers/apis/analytics-api