---
title: "Query Application Analytics"
url: "https://nov18-dev.movespot.fyi/apis/portal-application-analytics-2/versions/7eb4e759-6c13-4850-865d-25ae682ee61a/operations/query-application-analytics"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/portal-application-analytics-2/versions/7eb4e759-6c13-4850-865d-25ae682ee61a.md

# Query Application Analytics

`POST` `/api/v3/stats`

Operation ID: `query-application-analytics`

Query

## Request body

Content types: `application/json`

## Responses

- `200` - A response from an Application Analytics query.
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Portal Application Analytics
  version: 3.0.1
paths:
  /api/v3/stats:
    post:
      operationId: query-application-analytics
      summary: Query Application Analytics
      description: Query
      requestBody:
        description: Object describing the query sent to analytics API.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryApplicationAnalytics"
            examples:
              Query with a single metric:
                $ref: "#/components/examples/QueryExampleWithMetric"
              Query with a metric and dimension:
                $ref: "#/components/examples/QueryExampleWithMetricAndDimension"
              Query with a metric and two dimensions:
                $ref: "#/components/examples/QueryExampleWithMetricAndMultipleDimensions"
              Query with time dimension:
                $ref: "#/components/examples/QueryExampleWithTimeDimension"
      responses:
        "200":
          $ref: "#/components/responses/QueryResponse"
        "400":
          description: Bad Request
          content:
            application/problem+json:
              examples:
                BadRequestExample:
                  $ref: "#/components/examples/BadRequestExample"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              examples:
                UnauthorizedExample:
                  $ref: "#/components/examples/UnauthorizedExample"
        "403":
          $ref: "#/components/responses/Forbidden"
      security:
        - portalAccessToken: []
      tags:
        - Application Analytics
security:
  - portalAccessToken: []
components:
  schemas:
    QueryApplicationAnalytics:
      type: object
      properties:
        metrics:
          description: >
            A property of your API (such as request count or latency) that you
            wish to query on.

            Your chosen metric is aggregated within the specified dimensions,
            meaning that if you query 'request count by application', you'll
            receive the total number of requests each application received
            within the given time frame.
          type: array
          items:
            type: string
            enum:
              - request_count
              - request_per_minute
              - response_latency_average
              - response_size_average
              - response_size_sum
              - request_size_average
              - request_size_sum
          default:
            - request_count
          maxItems: 1
          minItems: 1
        dimensions:
          description: >
            The dimensions for the query.  A query may have up to 2 dimensions,
            including time.

            If no dimensions are provided, the report will simply return the
            provided metric aggregated across

            all available data.
          type: array
          items:
            type: string
            enum:
              - api
              - application
              - status_code
              - status_code_grouped
              - time
          default: []
          maxItems: 2
          minItems: 0
        granularity:
          description: >
            `granularity` is only valid for queries that include a time
            dimension, and it specifies the time buckets in for the returned
            data.
          type: string
          enum:
            - tenSecondly
            - thirtySecondly
            - minutely
            - fiveMinutely
            - tenMinutely
            - thirtyMinutely
            - hourly
            - twoHourly
            - twelveHourly
            - daily
            - weekly
            - trend
        time_range:
          description: The time range to query.
          default:
            type: relative
            time_range: 1h
          oneOf:
            - $ref: "#/components/schemas/RelativeTimeRangeDto"
            - $ref: "#/components/schemas/AbsoluteTimeRangeDto"
        filters:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/ApiFilter"
              - $ref: "#/components/schemas/ApplicationFilter"
              - $ref: "#/components/schemas/StatusCodeFilter"
              - $ref: "#/components/schemas/StatusCodeGroupedFilter"
          default: []
      additionalProperties: false
    RelativeTimeRangeDto:
      description: A duration representing a relative-to-now span of time. Generally
        the start time is floored to the requested granularity. Eg 7d from now,
        with 1day granularity initiated at 2024-01-08T17:11:00+05:00 will query
        for the time range from 2024-01-01T00:00:00+05:00 to
        2024-01-08T17:11:00+05:00. The exact start and end timestamps are
        returned in the result query in the meta.start and meta.end fields. If
        the granularity for the previous query was 1hour, it would query a time
        range from 2024-01-01T17:00:00+05:00 to 2024-01-08T17:11:00+05:00.
      type: object
      properties:
        tz:
          type: string
          default: Etc/UTC
        type:
          type: string
          enum:
            - relative
        time_range:
          type: string
          default: 1h
          enum:
            - 15m
            - 1h
            - 6h
            - 12h
            - 24h
            - 7d
            - 30d
            - current_week
            - current_month
            - previous_week
            - previous_month
      required:
        - type
        - time_range
    AbsoluteTimeRangeDto:
      description: A duration representing an exact start and end time.
      type: object
      properties:
        tz:
          type: string
          default: Etc/UTC
        type:
          type: string
          enum:
            - absolute
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
      required:
        - type
        - start
        - end
    ApiFilter:
      type: object
      properties:
        field:
          description: The dimension to filter.
          type: string
          enum:
            - api
        operator:
          $ref: "#/components/schemas/FilterType"
        value:
          description: |
            The UUIDs of the API product versions to include in the results.
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      additionalProperties: false
      required:
        - field
        - operator
        - value
    ApplicationFilter:
      type: object
      properties:
        field:
          description: The dimension to filter. If no application filter is provided the
            API will implicitly filter on the applications owned by the
            developer making the query request.
          type: string
          enum:
            - application
        operator:
          $ref: "#/components/schemas/FilterType"
        value:
          description: |
            The UUIDs of the dev portal applications to include in the results.
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      additionalProperties: false
      required:
        - field
        - operator
        - value
    StatusCodeFilter:
      type: object
      properties:
        field:
          description: The dimension to filter.
          type: string
          enum:
            - status_code
        operator:
          $ref: "#/components/schemas/FilterType"
        value:
          description: |
            Only include requests with specific status codes in the results.
          type: array
          items:
            type: integer
            minimum: 100
            maximum: 999
      additionalProperties: false
      required:
        - field
        - operator
        - value
    StatusCodeGroupedFilter:
      type: object
      properties:
        field:
          description: The dimension to filter.
          type: string
          enum:
            - status_code_grouped
        operator:
          $ref: "#/components/schemas/FilterType"
        value:
          description: |
            Only include the given groups of status codes in the results.
          type: array
          items:
            type: string
            pattern: ^\d[xX][xX]$
      additionalProperties: false
      required:
        - field
        - operator
        - value
    QueryResponseMeta:
      description: Query response metadata.
      type: object
      properties:
        display:
          description: >
            The blob represents how to interpret large UUID strings in the
            `data` response. The structure is records of dimension_id ->  ID ->
            entity metadata. Since entity names within Konnect may overlap, ids
            are returned and used for exact grouping. This blob may be used to
            join and display results in a more human friendly manner. Since IDs
            represent entities in the system at all points in time, historical
            data will still exist even if an entity is deleted. These such
            entities are marked with the `deleted` key.


            Another special case is the ____OTHER____ entity. When the limit of
            cardinality is reached for a second dimension, the system will group
            all other entities into the ____OTHER____ grouping. This prevents
            returning an overwhelming number of long tail entities.
          allOf:
            - $ref: "#/components/schemas/DisplayBlob"
        metric_names:
          description: The metric requested in query.
          type: array
          items:
            type: string
            enum:
              - request_count
              - request_per_minute
              - response_latency_average
              - response_size_average
              - response_size_sum
              - request_size_average
              - request_size_sum
          maxItems: 1
          minItems: 1
        metric_units:
          description: The unit of metric.
          type: object
          properties:
            request_count:
              type: string
              default: count
            request_per_minute:
              type: string
              default: count/minute
            response_latency_average:
              type: string
              default: ms
            response_size_average:
              type: string
              default: bytes
            response_size_sum:
              type: string
              default: bytes
            request_size_average:
              type: string
              default: bytes
            request_size_sum:
              type: string
              default: bytes
        start:
          description: |
            Start of the query time range.
          type: string
          format: date-time
        end:
          description: |
            End of the query time range.
          type: string
          format: date-time
        truncated:
          description: True if the limit of dimension values was reached and results were
            truncated. Limit value is 50.
          type: boolean
        limit:
          description: |
            Applied query cardinality limit.
          type: number
        granularity_ms:
          description: The resulting time bucket for the returned data. If `time` was not
            specified as a dimension, granularity is the duration of the query.
          type: integer
        query_id:
          description: Optional ID used to look up the query.
          type: string
      additionalProperties: false
    QueryResponseData:
      description: Query response data.
      type: array
      items:
        $ref: "#/components/schemas/QueryResponseEvent"
    ForbiddenError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 403
            title:
              example: Forbidden
            type:
              example: https://httpstatuses.com/403
            instance:
              example: kong:trace:1234567890
            detail:
              example: Forbidden
    FilterType:
      description: The type of filter to apply.  `in` filters will limit results to
        only the specified values, while `not_in` filters will exclude the
        specified values.
      type: string
      enum:
        - in
        - not_in
    DisplayBlob:
      type: object
      properties:
        api:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/DisplayEntry"
        application:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/DisplayEntry"
        status_code:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/DisplayEntry"
        status_code_grouped:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/DisplayEntry"
      example:
        applciation:
          bf16907c-8673-4f9d-aa83-111111111111:
            deleted: true
            name: bf16907c-8673-4f9d-aa83-111111111111
          bf16907c-8673-4f9d-aa83-1f2ea9215055:
            deleted: false
            name: Api v1 Beta
    QueryResponseEvent:
      description: A response record.
      type: object
      properties:
        event:
          description: Event within the response. Mapping from the requested metrics and
            dimensions to the values.
          type: object
          properties:
            request_count:
              description: The number or requests metric.
              type: integer
            request_per_minute:
              description: The number of requests per minute metric.
              type: number
            response_latency_average:
              description: Average response latency metric in milliseconds.
              type: number
            response_size_average:
              description: Average response size metric in bytes.
              type: number
            response_size_sum:
              description: Sum response size metric in bytes.
              type: number
            request_size_average:
              description: Average request size metric in bytes.
              type: number
            request_size_sum:
              description: Sum request size metric in bytes.
              type: number
            api:
              description: Id representing an API
              type: string
            application:
              description: Id representing an Application
              type: string
            status_code:
              description: Value for status_code.
              type: string
            status_code_grouped:
              description: Value for status_code_grouped.
              type: string
        timestamp:
          description: An ISO-8601 timestamp. If `time` was requested as a dimension this
            will be the start of the time bucket. If not specified this is the
            start time of the query.
          type: string
          format: date-time
          example: 2023-08-03T15:00:00.000Z
      additionalProperties: false
    BaseError:
      description: standard error
      type: object
      properties:
        status:
          description: >
            The HTTP status code of the error. Useful when passing the response

            body to child properties in a frontend UI. Must be returned as an
            integer.
          type: integer
          readOnly: true
        title:
          description: |
            A short, human-readable summary of the problem. It should not
            change between occurences of a problem, except for localization.
            Should be provided as "Sentence case" for direct use in the UI.
          type: string
          readOnly: true
        type:
          description: The error type.
          type: string
          readOnly: true
        instance:
          description: |
            Used to return the correlation ID back to the user, in the format
            kong:trace:<correlation_id>. This helps us find the relevant logs
            when a customer reports an issue.
          type: string
          readOnly: true
        detail:
          description: >
            A human readable explanation specific to this occurence of the
            problem.

            This field may contain request/entity data to help the user
            understand

            what went wrong. Enclose variable values in square brackets. Should
            be

            provided as "Sentence case" for direct use in the UI.
          type: string
          readOnly: true
      required:
        - status
        - title
        - instance
        - detail
      title: Error
    DisplayEntry:
      type: object
      properties:
        name:
          type: string
        deleted:
          type: boolean
        is_other_group:
          type: boolean
      example:
        deleted: true
        name: Api Alpha v1
      required:
        - name
  examples:
    QueryExampleWithMetric:
      value:
        time_range:
          type: relative
          time_range: 24h
          tz: EST
        metrics:
          - request_per_minute
        filters:
          - field: api
            operator: in
            value:
              - 417e47e8-ae7b-48a1-9b34-3f6835161de1
    QueryExampleWithMetricAndDimension:
      value:
        time_range:
          type: relative
          time_range: 24h
          tz: EST
        metrics:
          - response_size_average
        dimensions:
          - application
    QueryExampleWithMetricAndMultipleDimensions:
      value:
        time_range:
          type: relative
          time_range: 24h
          tz: EST
        metrics:
          - request_count
        dimensions:
          - application
          - status_code_grouped
        filters:
          - field: status_code_grouped
            operator: in
            value:
              - 2XX
              - 5XX
    QueryExampleWithTimeDimension:
      value:
        time_range:
          type: absolute
          start: 2023-08-04T14:08:00.00Z
          end: 2023-08-05T14:08:00.000Z
          tz: America/New_York
        granularity: hourly
        metrics:
          - response_size_average
        dimensions:
          - time
          - status_code_grouped
    BadRequestExample:
      value:
        status: 400
        title: Bad Request
        instance: kong:trace:9039922446017540182
        detail: "Malformed Query: field api_product is not allowed"
        invalid_parameters: []
    UnauthorizedExample:
      value:
        status: 401
        title: Unauthorized
        instance: kong:trace:9039922446017540182
        detail: "Developer to not have access to application:
          abe525e6-6baa-4cca-ba67-36dad0194a69"
        invalid_parameters: []
    ResponseExampleWithMetric:
      value:
        meta:
          display: {}
          metric_names:
            - request_per_minute
          metric_units:
            request_per_minute: count/minute
          start: 2023-08-04T14:08:00.000Z
          end: 2023-08-05T14:08:00.000Z
          granularity_ms: 86400000
          truncated: false
          limit: 50
          query_id: portal-api-3c0abb98-90bd-4e80-a495-ac268acc493e
        data:
          - event:
              request_per_minute: 1340.8666666666666
            timestamp: 2023-08-04T14:08:00.000Z
    ResponseExampleWithMetricAndDimension:
      value:
        meta:
          display:
            application:
              d5d51715-d4f2-4ca1-9920-26fd3977728a:
                name: Application 1
                deleted: false
              c8ae1321-7555-4280-b066-f5f181783d23:
                name: Application 2
                deleted: false
          metric_names:
            - response_latency_average
          metric_units:
            response_latency_average: ms
          start: 2023-08-03T15:00:00.000Z
          end: 2023-08-04T15:00:00.000Z
          granularity_ms: 86400000
          truncated: false
          limit: 50
          query_id: portal-api-3c0abb98-90bd-4e80-a495-ac268acc493e
        data:
          - event:
              application: 5d51715-d4f2-4ca1-9920-26fd3977728a
              response_latency_average: 250
            timestamp: 2023-08-03T15:00:00.000Z
          - event:
              application: c8ae1321-7555-4280-b066-f5f181783d23
              response_latency_average: 740
            timestamp: 2023-08-03T15:00:00.000Z
    ResponseExampleWithMetricAndMultipleDimensions:
      value:
        meta:
          start: 2023-08-03T15:00:00.000Z
          end: 2023-08-03T16:00:00.000Z
          granularity_ms: 3600000
          query_id: portal-api-4fad296e-da5e-41ed-af86-191440fe448e
          metric_names:
            - request_count
          metric_units:
            request_count: count
          display:
            application:
              d5d51715-d4f2-4ca1-9920-26fd3977728a:
                name: Application 1
                deleted: false
              c8ae1321-7555-4280-b066-f5f181783d23:
                name: Application 2
                deleted: false
            status_code_grouped:
              2XX:
                name: 2XX
                deleted: false
              5XX:
                name: 5XX
                deleted: false
          truncated: false
          limit: 50
        data:
          - event:
              application: d5d51715-d4f2-4ca1-9920-26fd3977728a
              status_code_grouped: 2XX
              request_count: 81447
            timestamp: 2023-08-03T15:00:00.000Z
          - event:
              application: d5d51715-d4f2-4ca1-9920-26fd3977728a
              status_code_grouped: 5XX
              request_count: 28468
            timestamp: 2023-08-03T15:00:00.000Z
          - event:
              application: c8ae1321-7555-4280-b066-f5f181783d23
              status_code_grouped: 2XX
              request_count: 45819
            timestamp: 2023-08-03T15:00:00.000Z
          - event:
              application: c8ae1321-7555-4280-b066-f5f181783d23
              status_code_grouped: 5XX
              request_count: 25041
            timestamp: 2023-08-03T15:00:00.000Z
    ResponseExampleWithTimeDimension:
      value:
        meta:
          start: 2023-08-03T15:00:00.000Z
          end: 2023-08-03T16:00:00.000Z
          granularity_ms: 3600000
          query_id: portal-api-3c0abb98-90bd-4e80-a495-ac268acc493e
          metric_names:
            - response_size_average
          metric_units:
            response_size_average: bytes
          display:
            status_code_grouped:
              2XX:
                name: 2XX
                deleted: false
              3XX:
                name: 3XX
                deleted: false
              4XX:
                name: 4XX
                deleted: false
              5XX:
                name: 5XX
                deleted: false
          truncated: false
          limit: 50
        data:
          - event:
              status_code_grouped: 2XX
              response_size_average: 590
            timestamp: 2023-08-03T15:00:00.000Z
          - event:
              status_code_grouped: 3XX
              response_size_average: 584
            timestamp: 2023-08-03T15:00:00.000Z
          - event:
              status_code_grouped: 4XX
              response_size_average: 629
            timestamp: 2023-08-03T15:00:00.000Z
          - event:
              status_code_grouped: 5XX
              response_size_average: 603
            timestamp: 2023-08-03T15:00:00.000Z
          - event:
              status_code_grouped: 2XX
              response_size_average: 590
            timestamp: 2023-08-03T16:00:00.000Z
          - event:
              status_code_grouped: 3XX
              response_size_average: 584
            timestamp: 2023-08-03T16:00:00.000Z
          - event:
              status_code_grouped: 4XX
              response_size_average: 628
            timestamp: 2023-08-03T16:00:00.000Z
          - event:
              status_code_grouped: 5XX
              response_size_average: 603
            timestamp: 2023-08-03T16:00:00.000Z
    ForbiddenExample:
      value:
        status: 403
        title: Forbidden
        instance: kong:trace:2723154947768991354
        detail: You do not have permission to perform this action
  responses:
    QueryResponse:
      description: A response from an Application Analytics query.
      content:
        application/json:
          schema:
            type: object
            properties:
              meta:
                $ref: "#/components/schemas/QueryResponseMeta"
              data:
                $ref: "#/components/schemas/QueryResponseData"
            additionalProperties: false
          examples:
            Response with a single metric:
              $ref: "#/components/examples/ResponseExampleWithMetric"
            Response with metric and dimension:
              $ref: "#/components/examples/ResponseExampleWithMetricAndDimension"
            Response with metric and two dimensions:
              $ref: "#/components/examples/ResponseExampleWithMetricAndMultipleDimensions"
            Response with time dimension:
              $ref: "#/components/examples/ResponseExampleWithTimeDimension"
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ForbiddenError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/ForbiddenExample"
  securitySchemes:
    portalAccessToken:
      type: apiKey
      in: cookie
      name: portalaccesstoken
      description: >
        The Developer portal cookie is meant to be used by the Developer API to
        authenticate with.
```
