Adobe Suite Calculated Metrics API

openapi: 3.2.0
info:
  description: "The endpoints described here are routed through analytics.adobe.io. In order to use these endpoints you must create an oAuth client that is subscribed to access the Adobe Analytics Reporting API. \n\n To view the API References for non-core Analytics 2.0 APIs, select the **API Reference** drop-down menu at the top of the page. \n\n Note: Adobe may add optional request and response members (name/value pairs) to existing API objects at any time and without notice or changes in versioning. Adobe recommends that you refer to the API documentation of any third-party tool you integrate with our APIs so that such additions are ignored in processing if not understood. If implemented properly, such additions are non-breaking changes for your implementation. Adobe will not remove parameters or add required parameters without first providing standard notification through release notes."
  title: Adobe Analytics Calculated Metrics API
  version: '2.0'
servers:
- url: https://analytics.adobe.io/api
tags:
- name: Calculated Metrics
paths:
  /{globalCompanyId}/calculatedmetrics:
    get:
      tags:
      - Calculated Metrics
      summary: Retrieve multiple calculated metrics
      description: "A calculated metric response will always include these default items: *id, name, description, rsid, owner, polarity, precision, type* \n\nOther attributes can be optionally requested through the 'expansion' field:\n\n* *modified*: Date that the metric was last modified (ISO 8601)\n* *definition*: Calculated metric definition as JSON object\n* *compatibility*: Products that the metric is compatible with\n* *reportSuiteName*: Also return the friendly report suite name for the RSID\n* *tags*: Gives all existing tags associated with the calculated metric\n\nFor more information, see the [Calculated Metrics API endpoint guide](https://developer.adobe.com/analytics-apis/docs/2.0/guides/endpoints/calculatedmetrics/)\n\n"
      operationId: findCalculatedMetrics
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: rsids
        in: query
        description: Filter list to only include calculated metrics tied to specified RSID list (comma-delimited)
        required: false
        schema:
          type: string
      - name: ownerId
        in: query
        description: Filter list to only include calculated metrics owned by the specified loginId
        required: false
        schema:
          type: integer
          format: int32
      - name: filterByIds
        in: query
        description: Filter list to only include calculated metrics in the specified list (comma-delimited list of IDs) (this is the same as calculatedMetricFilter, and is overwritten by calculatedMetricFilter
        required: false
        schema:
          type: string
      - name: toBeUsedInRsid
        in: query
        description: The report suite where the calculated metric intended to be used.  This report suite will be used to determine things like compatibility and permissions.  If it is not specified then the permissions will be calculated based on the union of all metrics authorized in all groups the user belongs to.  If the compatibility expansion is specified and toBeUsedInRsid is not then the compatibility returned is based off the compatibility from the last time the calculated metric was saved.
        required: false
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      - name: name
        in: query
        description: Filter list to only include calculated metrics that contains the Name
        required: false
        schema:
          type: string
      - name: tagNames
        in: query
        description: Filter list to only include calculated metrics that contains one of the tags
        required: false
        schema:
          type: string
      - name: favorite
        in: query
        description: Filter list to only include calculated metrics that are favorites
        required: false
        schema:
          type: boolean
      - name: approved
        in: query
        description: Filter list to only include calculated metrics that are approved
        required: false
        schema:
          type: boolean
      - name: limit
        in: query
        description: Number of results per page
        required: false
        schema:
          type: integer
          default: 10
      - name: page
        in: query
        description: Page number (base 0 - first page is "0")
        required: false
        schema:
          type: integer
          default: 0
      - name: sortDirection
        in: query
        description: Sort direction (ASC or DESC)
        required: false
        schema:
          type: string
          default: ASC
      - name: sortProperty
        in: query
        description: Property to sort by (name, modified_date, id is currently allowed)
        required: false
        schema:
          type: string
          default: id
      - name: expansion
        in: query
        description: Comma-delimited list of additional calculated metric metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - reportSuiteName
            - ownerFullName
            - modified
            - tags
            - definition
            - compatibility
            - categories
          enum:
          - reportSuiteName
          - ownerFullName
          - modified
          - tags
          - definition
          - compatibility
          - categories
      - name: includeType
        in: query
        description: Include additional calculated metrics not owned by user. The "all" option takes precedence over "shared"
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - all
            - shared
            - templates
          enum:
          - all
          - shared
          - templates
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnalyticsCalculatedMetric'
        '400':
          description: Unable to retrieve list of calculated metrics shared with user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '401':
          description: Owner filter error; user specified is not in the same company as the requesting user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '403':
          description: Requesting non-shared calculated metrics for other users is restricted to admin users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '500':
          description: External API error; Calculated metric retrieval failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
    post:
      tags:
      - Calculated Metrics
      summary: Create a new calculated metric
      description: "Creates a new calculated metric. The following attributes are available when creating a calculated metric:\n\nIMPORTANT: Required Fields: name, definition, rsid\n\nOptional fields: description\n\nExample definition for use in testing API below (\"Visits per visitor\"):\n\n```json\n\n\"definition\": {\n      \"formula\": {\n        \"func\": \"divide\",\n        \"col1\": {\n          \"func\": \"metric\",\n          \"name\": \"metrics/visits\",\n          \"description\": \"Visits\"\n        },\n        \"col2\": {\n          \"func\": \"metric\",\n          \"name\": \"metrics/visitors\",\n          \"description\": \"Unique Visitors\"\n        }\n      },\n      \"func\": \"calc-metric\",\n      \"version\": [\n        1,\n        0,\n        0\n      ]\n    }\n```\n\nA calculated metric response will always include these default items:* id, name, description, rsid, owner* \n\nAdditional attributes can be optionally requested in the 'expansion' field as described in the GET calculated metrics section."
      operationId: calculatedmetrics_createCalculatedMetric
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      - name: expansion
        in: query
        description: Comma-delimited list of additional calculated metric metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - reportSuiteName
            - ownerFullName
            - modified
            - tags
            - definition
            - compatibility
            - categories
          enum:
          - reportSuiteName
          - ownerFullName
          - modified
          - tags
          - definition
          - compatibility
          - categories
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsCalculatedMetric'
        '400':
          description: Invalid input; name, rsid, and definition are all required. Definition must be formatted as a JSON Object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '500':
          description: External API error; Calculated metric create or retrieval failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsCalculatedMetric'
        description: JSON-formatted Object containing key/value pairs for calculated metric creation.
  /{globalCompanyId}/calculatedmetrics/functions:
    get:
      tags:
      - Calculated Metrics
      summary: Retrieve calculated metric functions
      description: ''
      operationId: calculatedmetrics_getCalculatedMetricFunctions
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalcMetricFunction'
        '500':
          description: External API error; Calculated metric functions retrieval failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
  /{globalCompanyId}/calculatedmetrics/functions/{id}:
    get:
      tags:
      - Calculated Metrics
      summary: Retrieve a calculated metric function by ID
      description: ''
      operationId: calculatedmetrics_getCalculatedMetricFunction
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: id
        in: path
        description: The function ID to retrieve
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalcMetricFunction'
        '404':
          description: Calculated metric function not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '500':
          description: External API error; Calculated metric function retrieval failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
  /{globalCompanyId}/calculatedmetrics/validate:
    post:
      tags:
      - Calculated Metrics
      summary: Validate a calculated metric definition
      description: ''
      operationId: calculatedmetrics_validateCalculatedMetric
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      - name: migrating
        in: query
        description: Include migration functions in validation
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsCalculatedMetric'
        '400':
          description: Invalid input; name, rsid, and definition are all required. Definition must be formatted as a JSON Object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '500':
          description: External API error; Calculated metric validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsCalculatedMetric'
        description: JSON-formatted Object containing key/value pairs for calculated metric validation.
  /{globalCompanyId}/calculatedmetrics/{id}:
    get:
      tags:
      - Calculated Metrics
      summary: Retrieve a single calculated metric by ID
      description: "A calculated metric response will always include these default items: *id, name, description, rsid, owner, polarity, precision, type* \n\nOther attributes can be optionally requested through the 'expansion' field:\n\n* *modified*: Date that the metric was last modified (ISO 8601)\n* *definition*: Calculated metric definition as JSON object\n* *compatibility*: Products that the metric is compatible with\n* *reportSuiteName*: Also return the friendly report suite name for the RSID\n* *tags*: Gives all existing tags associated with the calculated metric\n\nFor more information, see the [Calculated Metrics API endpoint guide](https://developer.adobe.com/analytics-apis/docs/2.0/guides/endpoints/calculatedmetrics/)\n\n"
      operationId: findOneCalculatedMetric
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: id
        in: path
        description: The calculated metric ID to retrieve
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      - name: expansion
        in: query
        description: Comma-delimited list of additional calculated metric metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - reportSuiteName
            - ownerFullName
            - modified
            - tags
            - definition
            - compatibility
            - categories
          enum:
          - reportSuiteName
          - ownerFullName
          - modified
          - tags
          - definition
          - compatibility
          - categories
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsCalculatedMetric'
        '403':
          description: Requesting non-shared calculated metrics for other users is restricted to admin users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '500':
          description: External API error; calculated metric retrieval failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
    put:
      tags:
      - Calculated Metrics
      summary: Update an existing calculated metric
      description: "The following fields can be modified through this endpoint: <br/><b>name, description, definition, owner, rsid</b>\nExample \"defintion\" for use in testing API below (\"Visits per visitor\"):<br/>\n\"definition\": {\n      \"formula\": {\n        \"func\": \"divide\",\n        \"col1\": {\n          \"func\": \"metric\",\n          \"name\": \"metrics/visits\",\n          \"description\": \"Visits\"\n        },\n        \"col2\": {\n          \"func\": \"metric\",\n          \"name\": \"metrics/visitors\",\n          \"description\": \"Unique Visitors\"\n        }\n      },\n      \"func\": \"calc-metric\",\n      \"version\": [\n        1,\n        0,\n        0\n      ]\n    }<br/><br/>Response will be the newly modified calculated metric object after the update request completes.<br/><br/><b><span style=\"text-decoration: underline;\">CalculatedMetricResponse</span></b><br/>A calculated metric response will always include these default items:* id, name, description, rsid, owner* \n\nAdditional attributes can be optionally requested in the 'expansion' field as described in the GET calculated metrics section."
      operationId: calculatedmetrics_updateCalculatedMetric
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: id
        in: path
        description: Calculated Metric ID to be updated
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      - name: expansion
        in: query
        description: Comma-delimited list of additional calculated metric metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - reportSuiteName
            - ownerFullName
            - modified
            - tags
            - definition
            - compatibility
            - categories
          enum:
          - reportSuiteName
          - ownerFullName
          - modified
          - tags
          - definition
          - compatibility
          - categories
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsCalculatedMetric'
        '400':
          description: Definition must be formatted as a JSON Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '401':
          description: Company mismatch; calculated metric ownership can only be transferred within the same organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '403':
          description: User does not have permission to update this calculated metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
        '500':
          description: External API error; Calculated metric update or retrieval failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsCalculatedMetric'
        description: JSON-formatted Object containing key/value pairs to be updated.
    delete:
      tags:
      - Calculated Metrics
      summary: Delete calculated metrics by ID
      description: ''
      operationId: calculatedmetrics_deleteCalculatedMetric
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: id
        in: path
        description: The calculated metric ID to be deleted
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '500':
          description: External API error; Calculated metric delete failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedMetricErrorStatus'
components:
  schemas:
    AnalyticsCalculatedMetric:
      type: object
      required:
      - definition
      properties:
        id:
          type: string
          description: System generated id
          readOnly: true
        name:
          type: string
        description:
          type: string
        rsid:
          type: string
          description: The report suite id for which the component was created/updated
        reportSuiteName:
          type: string
          description: The report suite name for which the component was created/updated
          readOnly: true
        owner:
          $ref: '#/components/schemas/Owner'
        polarity:
          type: string
          description: Set metric polarity, which indicates whether it's good or bad if a given metric goes up. Default=positive
          enum:
          - positive
          - negative
        precision:
          type: integer
          format: int32
          description: Number of decimal places to include in calculated metric result
        type:
          type: string
          enum:
          - CURRENCY
          - TIME
          - DECIMAL
          - PERCENT
        definition:
          description: Calculated metric definition object
          $ref: '#/components/schemas/CalculatedMetricDef'
        categories:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        siteTitle:
          type: string
        modified:
          type: string
          format: date-time
        created:
          type: string
          format: date-time
          description: Calculated metric creation date
          readOnly: true
    TaggedComponent:
      type: object
      properties:
        componentType:
          type: string
        componentId:
          type: string
        tags:
          type: array
          items:
            type: string
    DeleteResponse:
      type: object
      properties:
        result:
          type: string
        message:
          type: string
    CalcMetricFunctionDef:
      type: object
      properties:
        func:
          type: string
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/CalcMetricFunctionParameter'
        formula:
          type: object
          additionalProperties:
            type: object
        version:
          type: array
          items:
            type: integer
            format: int32
    CalcMetricFunctionParameter:
      type: object
      properties:
        func:
          type: string
        name:
          type: string
        type:
          type: string
        friendlyNameKey:
          type: string
        descKey:
          type: string
        friendlyName:
          type: string
        description:
          type: string
        default-value:
          type: object
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: the tag id
        name:
          type: string
          description: 'the tag name '
        description:
          type: string
          description: the tag description
        components:
          type: array
          description: the list of components that have been tagged with this tag
          uniqueItems: true
          items:
            $ref: '#/components/schemas/TaggedComponent'
      description: Tag Model
    CalcMetricFunction:
      type: object
      properties:
        id:
          type: string
          description: Calculated Metric Function ID
        category:
          type: string
          description: Calculated Metric Function category
        persistable:
          type: boolean
          description: If a Calculated Metric Function is persistable
        name:
          type: string
          description: Calculated Metric Function name
        namespace:
          type: string
          description: Calculated Metric Function namespace
        description:
          type: string
          description: Calculated Metric Function description
        exampleKey:
          type: string
          description: Calculated Metric Function example key
        example:
          type: string
          description: Calculated Metric Function example
        definition:
          description: Calculated Metric Function definition
          $ref: '#/components/schemas/CalcMetricFunctionDef'
    CalculatedMetricErrorStatus:
      type: object
      properties:
        errorCode:
          type: string
          enum:
          - no_feature_access_to_advanced_calculated_metrics
          - invalid_metric_access
          - method_not_allowed
          - resource_conflict
          - invalid_access
          - resource_temporarily_unavailable
          - external_api_failure
          - aam_failure
          - resource_already_exists
          - invalid_state
          - invalid_json_input
          - invalid_parameters
          - invalid_dimension_access
          - unsupported_data_type
          - resource_not_found
          - insufficient_access
          - health_check_error
          - invalid_data
          - unexpected_error
          - external_api_error
          - unsupported_resource
          - io_error
          - invalid_request
          - invalid_client_id
          - unauthorized
          - authorization_error
          - invalid_token
          - insufficient_scope
          - bluecoat_unauthorized
        errorDescription:
          type: string
        errorId:
          type: string
        errorDetails:
          type: object
          additionalProperties:
            type: object
        rootCauseService:
          type: string
    Owner:
      type: object
      required:
      - id
      properties:
        id:
          type: integer
          format: int32
          description: the login id of the owner
        name:
          type: string
          description: the friendly full login name of the owner, included when the expansion parameter ownerFullName is true
        login:
          type: string
          description: the friendly full login name of the owner, included when the expansion parameter ownerFullName is true
    CalculatedMetricDef:
      type: object
  parameters:
    authorization:
      name: Authorization
      in: header
      description: The access token copied from your AA API client integration, prefixed with "Bearer ".
      required: true
      schema:
        type: string
    x-api-key:
      name: x-api-key
      in: header
      description: The API key copied from your AA API client integration. For more information on how to obtain this value, see [Getting started with the Analytics API](https://developer.adobe.com/analytics-apis/docs/2.0/guides/).
      required: true
      schema:
        type: string