---
title: "Explore metrics in the analyticcs platform"
url: "https://nov18-dev.movespot.fyi/apis/konnect-explore-endpoint-dev-4/versions/0f8ac6c3-1f91-4060-82fe-5fd3fe57d9ec/operations/ExploreController_exploreV2"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-explore-endpoint-dev-4/versions/0f8ac6c3-1f91-4060-82fe-5fd3fe57d9ec.md

# Explore metrics in the analyticcs platform

`POST` `/explore`

Operation ID: `ExploreController_exploreV2`

Post a query to the endpoint to retrieve aggregated metrics down to the minute. Data can be requested to group by any 2 dimensions, and any number of filter conditions.

## Request body (required)

Content types: `application/json`

## Responses

- `200` - Aggregated results of the query
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden

## OpenAPI definition

```yaml
openapi: 3.0.2
info:
  title: Konnect Explore Endpoint
  version: 4.0.0
servers:
  - url: https://us.api.konghq.com/v4
    description: United-States Production region
  - url: https://eu.api.konghq.com/v4
    description: Europe Production region
  - url: https://au.api.konghq.com/v4
    description: Australia Production region
  - url: https://me.api.konghq.com/v4
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v4
    description: India Production region
  - url: https://sg.api.konghq.com/v4
    description: Singapore Production region
paths:
  /explore:
    post:
      operationId: ExploreController_exploreV2
      summary: Explore metrics in the analyticcs platform
      description: Post a query to the endpoint to retrieve aggregated metrics down to
        the minute. Data can be requested to group by any 2 dimensions, and any
        number of filter conditions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExploreV2Dto"
      responses:
        "200":
          description: Aggregated results of the query
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExploreResultV2"
        "400":
          description: Bad Request
          content:
            application/problem+json:
              examples:
                BadRequestExample:
                  $ref: "#/components/examples/BadRequestExample"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
      tags:
        - Explore
components:
  schemas:
    ExploreV2Dto:
      description: A query to launch at the API
      type: object
      properties:
        metrics:
          description: List of aggregated metrics to collect across the requested time span.
          type: array
          items:
            type: string
            enum:
              - request_count
              - request_per_minute
              - response_latency_p99
              - response_latency_p95
              - response_latency_p50
              - response_latency_average
              - upstream_latency_p99
              - upstream_latency_p95
              - upstream_latency_p50
              - upstream_latency_average
              - kong_latency_p99
              - kong_latency_p95
              - kong_latency_p50
              - kong_latency_average
              - response_size_p99
              - response_size_p95
              - response_size_p50
              - request_size_p99
              - request_size_p95
              - request_size_p50
              - request_size_average
              - response_size_average
          example:
            - request_count
        dimensions:
          description: List of attributes or entity types to group by.
          type: array
          items:
            type: string
            enum:
              - api_product
              - api_product_version
              - application
              - consumer
              - control_plane
              - control_plane_group
              - data_plane_node
              - gateway_service
              - route
              - status_code
              - status_code_grouped
              - time
          example:
            - status_code_grouped
          maxItems: 2
          minItems: 0
        filters:
          description: A list of filters to apply to the query.
          type: array
          items:
            $ref: "#/components/schemas/ExploreFilter"
        granularity:
          description: >
            Force time grouping into buckets of the specified duration.  Only
            has an effect if "time" is in the "dimensions" list.


            If "trend" is chosen, the time range covered by the query will be
            twice the specified time range, and the granularity will be set such
            that two time buckets are returned, one for the given time range and
            one for the same time range prior.

            For example:


            time range: last 24 hours

            granularity: trend


            will return 2 time buckets (assuming both have data):


            - 48 hours ago to 24 hours ago

            - 24 hours ago to now


            Another example:


            time range: 2020-05-01 to 2020-05-15

            granularity: trend


            will return 2 time buckets:


            - 2020-04-15 through 2020-04-30

            - 2020-05-01 through 2020-05-15


            The granularity of the result may be coarser than requested.  The
            finest allowed granularity depends on the query's time range: data
            farther in the past may have coarser granularity.  The exact result
            granularity will be reported in the response `meta.granularity_ms`
            field.


            If granularity is not specified and "time" is in the dimensions
            list, a default will be chosen based on the time range requested.
          type: string
          enum:
            - minute
            - hour
            - day
            - week
            - trend
        time_range:
          description: The time range to query.
          default:
            type: relative
            time_range: 1h
          discriminator:
            propertyName: type
            mapping:
              relative: "#/components/schemas/RelativeTimeRangeDtoV2"
              absolute: "#/components/schemas/AbsoluteTimeRangeDtoV2"
          oneOf:
            - $ref: "#/components/schemas/RelativeTimeRangeDtoV2"
            - $ref: "#/components/schemas/AbsoluteTimeRangeDtoV2"
        meta:
          type: object
      example:
        time_range:
          type: relative
          time_range: 24h
          tz: EST
        dimensions:
          - time
          - gateway_service
        filters:
          - type: in
            dimension: control_plane
            values:
              - d5ac5d88-efed-4e10-9dfe-0b0a6646c219
        granularity: hour
        metrics:
          - response_latency_p99
          - response_latency_p95
          - response_latency_p50
      required:
        - metrics
    ExploreResultV2:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/GroupByResult"
          readOnly: true
        meta:
          allOf:
            - $ref: "#/components/schemas/QueryResponseMeta"
          readOnly: true
      required:
        - data
        - meta
    ExploreFilter:
      description: A filter that specifies which data to include in the query
      type: object
      properties:
        dimension:
          type: string
          example: status_code
          enum:
            - api_product
            - api_product_version
            - application
            - consumer
            - control_plane
            - control_plane_group
            - data_plane_node
            - gateway_service
            - route
            - status_code
            - status_code_grouped
        type:
          type: string
          example: in
          enum:
            - in
            - not_in
            - selector
        values:
          type: array
          items:
            type: string
      required:
        - dimension
        - type
        - values
    RelativeTimeRangeDtoV2:
      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_ms and meta.end_ms
        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
    AbsoluteTimeRangeDtoV2:
      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
    GroupByResult:
      type: object
      properties:
        timestamp:
          type: string
          readOnly: true
        event:
          type: object
          readOnly: true
      example:
        event:
          gateway_service: d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-1f2ea9215055
          request_count: 1000
          response_latency_p99: 23
        timestamp: 2024-01-16T00:00:00Z
      required:
        - timestamp
        - event
    QueryResponseMeta:
      type: object
      properties:
        start_ms:
          type: number
          readOnly: true
        end_ms:
          type: number
          readOnly: true
        display:
          allOf:
            - $ref: "#/components/schemas/DisplayBlob"
          readOnly: true
        metric_units:
          allOf:
            - $ref: "#/components/schemas/MetricUnitDto"
          readOnly: true
        granularity:
          type: number
          readOnly: true
        granularity_ms:
          type: number
          readOnly: true
        truncated:
          type: boolean
          readOnly: true
        limit:
          type: number
          readOnly: true
        query_id:
          type: string
          readOnly: true
      example:
        start_ms: 1705428000000
        end_ms: 1705429000000
        display:
          gateway_service:
            d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-111111111111:
              id: d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-111111111111
              deleted: true
              name: Gateway Service Alpha
            d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-1f2ea9215055:
              id: d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-1f2ea9215055
              deleted: false
              name: Gateway Service Beta
        metric_units:
          request_count: cnt
          response_latency_p99: ms
        granularity_ms: 60000
        truncated: false
        limit: 50
        query_id: requested-query-id
      required:
        - start_ms
        - end_ms
        - display
        - metric_units
        - granularity_ms
        - truncated
        - limit
        - query_id
    UnauthorizedError:
      allOf:
        - $ref: "#/components/schemas/BaseError"
        - type: object
          properties:
            status:
              example: 401
            title:
              example: Unauthorized
            type:
              example: https://httpstatuses.com/401
            instance:
              example: kong:trace:1234567890
            detail:
              example: Invalid credentials
    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
    DisplayBlob:
      type: object
      properties: {}
      example:
        gateway_service:
          d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-111111111111:
            id: d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-111111111111
            deleted: true
            name: Gateway Service Alpha
          d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-1f2ea9215055:
            id: d5ac5d88-efed-4e10-9dfe-0b0a6646c219:bf16907c-8673-4f9d-aa83-1f2ea9215055
            deleted: false
            name: Gateway Service Beta
    MetricUnitDto:
      type: object
      properties: {}
      example:
        request_count: cnt
        response_latency_p99: ms
    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
  examples:
    BadRequestExample:
      value:
        status: 400
        title: Invalid Request
        instance: kong:trace:6591723055278037644
        detail: Invalid Parameters
        invalid_parameters:
          - field: time_range.time_range
            rule: unknown_property
            choices: []
            reason: property time_range should not exist
          - field: time_range.start_date
            rule: is_date
            choices: []
            reason: start must be a valid date in ISO format
          - field: time_range.end_date
            rule: is_date
            choices: []
            reason: end must be a valid date in ISO format
    UnauthorizedExample:
      value:
        status: 401
        title: Unauthorized
        instance: kong:trace:8347343766220159418
        detail: Unauthorized
    ForbiddenExample:
      value:
        status: 403
        title: Forbidden
        instance: kong:trace:2723154947768991354
        detail: You do not have permission to perform this action
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/UnauthorizedError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/UnauthorizedExample"
    Forbidden:
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ForbiddenError"
          examples:
            UnauthorizedExample:
              $ref: "#/components/examples/ForbiddenExample"
```
