openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Jobs 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: Jobs
  description: Analytics jobs represent asynchronous data retrieval operations. Use the job ID returned from POST endpoints to fetch results via the job data endpoint.
paths:
  /analytics/v2/job/{jobId}/data:
    get:
      operationId: getJobData
      summary: Get analytics job results
      description: Retrieves the results of an asynchronous analytics job using the jobId returned from an analytics POST endpoint. Poll this endpoint until the job status is completed to retrieve the full dataset.
      tags:
      - Jobs
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/JobId'
      - $ref: '#/components/parameters/Skip'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: The analytics job results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
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'
    NotFound:
      description: The requested job was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of records to return.
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
    JobId:
      name: jobId
      in: path
      required: true
      description: The unique identifier of the analytics job returned from a POST endpoint.
      schema:
        type: string
    OrganizationUid:
      name: organization_uid
      in: header
      required: true
      description: The unique identifier of the organization.
      schema:
        type: string
    Skip:
      name: skip
      in: query
      description: Number of records to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    JobData:
      type: object
      description: The results of a completed analytics job.
      properties:
        jobId:
          type: string
          description: The unique identifier of the analytics job.
        status:
          type: string
          description: Current status of the job.
          enum:
          - queued
          - processing
          - completed
          - failed
        data:
          type: array
          description: Array of analytics data records.
          items:
            type: object
            description: An individual analytics data point with metric values and dimensions.
        total:
          type: integer
          description: Total number of records available for this job.
    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.
  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