openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Subscription Usage 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: Subscription Usage
  description: Subscription usage analytics provide metrics on Launch project, environment, and domain counts relative to the organization's plan limits.
paths:
  /analytics/v2/subscription-usage:
    post:
      operationId: getSubscriptionUsage
      summary: Get subscription usage metrics
      description: Returns metrics on the organization's Launch resource consumption including the total number of projects, environments, and custom domains relative to plan limits. Queues an async job and returns a jobId for result retrieval.
      tags:
      - Subscription Usage
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsRequest'
      responses:
        '200':
          description: Job queued successfully with a jobId for result retrieval.
          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.
  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