openapi: 3.1.0
info:
  title: Adobe Analytics Annotations Reports API
  description: The Adobe Analytics 2.0 APIs provide programmatic access to data, reports, and administration features within Adobe Analytics. You can perform almost any action available in the Analytics user interface, including reporting, segment management, calculated metrics, dimensions, and component administration.
  version: '2.0'
  contact:
    name: Adobe Analytics Support
    url: https://developer.adobe.com/analytics-apis/docs/2.0/support/
  termsOfService: https://www.adobe.com/legal/terms.html
  x-last-validated: '2026-04-18'
servers:
- url: https://analytics.adobe.io/api/{globalCompanyId}
  description: Adobe Analytics Production API
  variables:
    globalCompanyId:
      description: The global company ID for your Adobe Analytics organization
      default: YOUR_GLOBAL_COMPANY_ID
security:
- bearerAuth: []
  apiKey: []
tags:
- name: Reports
  description: Run analytics reports and retrieve data
paths:
  /reports:
    post:
      operationId: runReport
      summary: Adobe Analytics Run a Report
      description: Runs an analytics report based on the provided report request definition. The request body specifies metrics, dimensions, date ranges, filters, and other parameters to define the report output.
      tags:
      - Reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
            examples:
              RunreportRequestExample:
                summary: Default runReport request
                x-microcks-default: true
                value:
                  rsid: '500123'
                  locale: example_value
                  globalFilters:
                  - type: dateRange
                    dateRange: example_value
                    segmentId: '500123'
                    dimension: example_value
                    itemId: '500123'
                  metricContainer:
                    metrics:
                    - {}
                    metricFilters:
                    - {}
                  dimension: example_value
                  settings:
                    limit: 10
                    page: 10
                    nonesBehavior: exclude-nones
                  statistics: example_value
      responses:
        '200':
          description: Report results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
              examples:
                Runreport200Example:
                  summary: Default runReport 200 response
                  x-microcks-default: true
                  value:
                    totalPages: 42
                    numberOfElements: 10
                    rows:
                    - itemId: '500123'
                      value: example_value
                      data: {}
                    columns: example_value
                    summaryData: example_value
        '400':
          description: Invalid request body or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Runreport400Example:
                  summary: Default runReport 400 response
                  x-microcks-default: true
                  value:
                    errorCode: example_value
                    errorDescription: example_value
                    errorId: '500123'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Runreport401Example:
                  summary: Default runReport 401 response
                  x-microcks-default: true
                  value:
                    errorCode: example_value
                    errorDescription: example_value
                    errorId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ReportSettings:
      type: object
      description: Settings that control report output behavior
      properties:
        limit:
          type: integer
          description: Maximum number of rows to return
          default: 50
          example: 10
        page:
          type: integer
          description: Page number (zero-indexed)
          default: 0
          example: 10
        nonesBehavior:
          type: string
          description: How to handle None values
          enum:
          - exclude-nones
          - return-nones
          example: exclude-nones
    MetricContainer:
      type: object
      required:
      - metrics
      description: Container defining the metrics to include in a report
      properties:
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/ReportMetric'
          example: []
        metricFilters:
          type: array
          description: Filters applied at the metric level
          items:
            $ref: '#/components/schemas/ReportFilter'
          example: []
    ReportRow:
      type: object
      description: A single row in a report result
      properties:
        itemId:
          type: string
          description: The dimension item ID
          example: '500123'
        value:
          type: string
          description: The dimension item display value
          example: example_value
        data:
          type: array
          description: Metric values for this row, in column order
          items:
            type: number
          example: []
    ErrorResponse:
      type: object
      description: Error response from the API
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
          example: example_value
        errorDescription:
          type: string
          description: Human-readable error message
          example: example_value
        errorId:
          type: string
          description: Unique ID for tracking this error
          example: '500123'
    ReportResponse:
      type: object
      description: The result of an analytics report request
      properties:
        totalPages:
          type: integer
          description: Total number of result pages
          example: 42
        numberOfElements:
          type: integer
          description: Number of rows in this response
          example: 10
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ReportRow'
          example: []
        columns:
          type: object
          description: Column metadata for the report
          example: example_value
        summaryData:
          type: object
          description: Totals and summary statistics
          example: example_value
    ReportFilter:
      type: object
      required:
      - type
      description: A filter applied to a report
      properties:
        type:
          type: string
          description: Filter type
          enum:
          - dateRange
          - breakdown
          - segment
          example: dateRange
        dateRange:
          type: string
          description: ISO 8601 date range (e.g. 2024-01-01T00:00:00/2024-01-31T23:59:59)
          example: example_value
        segmentId:
          type: string
          description: ID of an existing segment to apply as a filter
          example: '500123'
        dimension:
          type: string
          description: Dimension for breakdown filter
          example: example_value
        itemId:
          type: string
          description: Dimension item ID for breakdown filter
          example: '500123'
    ReportRequest:
      type: object
      required:
      - rsid
      - globalFilters
      - metricContainer
      description: Definition of an analytics report request
      properties:
        rsid:
          type: string
          description: The report suite ID to run the report against
          example: examplersid
        locale:
          type: string
          description: Locale for response labels
          example: en_US
        globalFilters:
          type: array
          description: List of global filters applied to the entire report
          items:
            $ref: '#/components/schemas/ReportFilter'
          example: []
        metricContainer:
          $ref: '#/components/schemas/MetricContainer'
        dimension:
          type: string
          description: The primary dimension ID for the report (e.g. variables/page)
          example: variables/page
        settings:
          $ref: '#/components/schemas/ReportSettings'
        statistics:
          type: object
          description: Statistical settings for the report
          example: example_value
    ReportMetric:
      type: object
      required:
      - id
      description: A metric included in a report request
      properties:
        id:
          type: string
          description: The metric ID (e.g. metrics/visits)
          example: abc123
        columnId:
          type: string
          description: Column identifier for this metric in the response
          example: '500123'
        filters:
          type: array
          description: Metric-level filter IDs referencing metricFilters
          items:
            type: string
          example: []
        sort:
          type: string
          description: Sort direction for this metric
          enum:
          - ASC
          - DESC
          example: ASC
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token from Adobe IMS
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Adobe Developer Console API key
externalDocs:
  description: Adobe Analytics 2.0 API Documentation
  url: https://developer.adobe.com/analytics-apis/docs/2.0/