contentstack URL Analytics API

openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts URL 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: URL Analytics
  description: URL analytics show request volume broken down by specific URLs to identify high-traffic content and optimize delivery.
paths:
  /analytics/v2/top-urls:
    post:
      operationId: getTopUrls
      summary: Get top URLs by request count
      description: Returns the most frequently requested URLs within the organization's Contentstack delivery infrastructure over the specified time period.
      tags:
      - URL Analytics
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsRequest'
      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.
  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