---
title: "New Custom Report"
url: "https://nov18-dev.movespot.fyi/apis/konnect-analytics-reports-dev-2/versions/370301af-a74b-40da-a34b-13e279afe451/operations/create-report"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-analytics-reports-dev-2/versions/370301af-a74b-40da-a34b-13e279afe451.md

# New Custom Report

`POST` `/reports`

Operation ID: `create-report`

Creates a new custom report.

## Request body

Content types: `application/json`

## Responses

- `201` - A response including a single report.
- `400` - Bad Request
- `403` - Permission denied
- `429` - Too many requests

## OpenAPI definition

```yaml
openapi: 3.0.2
info:
  title: Konnect Analytics Reports
  version: 2.0.0
servers:
  - url: https://us.api.konghq.com/v2
    description: United-States Production region
  - url: https://eu.api.konghq.com/v2
    description: Europe Production region
  - url: https://au.api.konghq.com/v2
    description: Australia Production region
  - url: https://me.api.konghq.com/v2
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v2
    description: India Production region
  - url: https://sg.api.konghq.com/v2
    description: Singapore Production region
paths:
  /reports:
    post:
      operationId: create-report
      summary: New Custom Report
      description: Creates a new custom report.
      requestBody:
        $ref: "#/components/requestBodies/CreateReport"
      responses:
        "201":
          $ref: "#/components/responses/ReportSingle"
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/PermissionDenied"
        "429":
          $ref: "#/components/responses/TooManyRequests"
      tags:
        - Custom Reports
components:
  requestBodies:
    CreateReport:
      description: >-
        The request schema for the create report request.


        If you pass the same `name` and `description` of an existing report in
        the request, a report with the same `name` and `description` will be
        created. The two reports will have different `id` values to
        differentiate them.


        Note that all fields are optional: if you pass an empty JSON object as
        the request (`{}`), a new report will be created with a default
        configuration.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Report"
          examples:
            basicBarChart:
              summary: Bar chart of status codes by API product for the past 24 hours
              description: A vertical bar chart grouping data first by API product, then by
                status code, for the past 24 hours.
              value:
                name: Status codes by service
                chart_type: VERTICAL_BAR
                time_range:
                  type: RELATIVE
                  time_period: 24H
                query:
                  metrics:
                    - REQUEST_COUNT
                  dimensions:
                    - API_PRODUCT
                    - STATUS_CODE
            barChartWithFilter:
              summary: Bar chart of status codes for one product
              description: A horizontal bar chart, showing status codes, filtered down to only
                one API product.
              value:
                name: Status codes for product A
                chart_type: HORIZONTAL_BAR
                query:
                  metrics:
                    - REQUEST_COUNT
                  dimensions:
                    - STATUS_CODE
                  filter:
                    - dimension: API_PRODUCT
                      type: IN
                      values:
                        - 7f9fd312-a987-4628-b4c5-bb4f4fddd5f7
            lineChartWithPercentiles:
              summary: Line chart of p99 latencies by application
              description: A line chart showing p99 latency over time for each application for
                the past 24 hours.
              value:
                name: Latency by application
                chart_type: LINE
                time_range:
                  type: RELATIVE
                  time_period: 24H
                query:
                  metrics:
                    - RESPONSE_LATENCY_P99
                  granularity: HOURLY
                  dimensions:
                    - TIME
                    - APPLICATION
            lineChartWithFixedPeriod:
              summary: Line chart of p99 latencies by service
              description: A line chart showing p99 latency for the first week of 2023.
              value:
                name: Latency by service
                chart_type: LINE
                time_range:
                  type: ABSOLUTE
                  start: 2023-01-01
                  end: 2023-01-07
                query:
                  metrics:
                    - RESPONSE_LATENCY_P99
                  dimensions:
                    - TIME
                    - API_PRODUCT
  responses:
    ReportSingle:
      description: A response including a single report.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Report"
    BadRequest:
      description: Bad Request
      content:
        application/problem+json:
          schema:
            description: The error object
            type: object
            properties:
              type:
                description: Documentation for this error.
                type: string
              status:
                description: The HTTP response code
                type: integer
                example: 400
              title:
                description: The Error response
                type: string
                example: Bad Request
              instance:
                description: The Konnect traceback ID.
                type: string
                example: konnect:trace:3674017986744198214
              invalid_parameters:
                description: An array of objects that contains information related to the error
                  response.
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    reason:
                      type: string
                    rule:
                      type: string
    PermissionDenied:
      description: Permission denied
      content:
        application/problem+json:
          schema:
            description: The error object.
            type: object
            properties:
              type:
                description: Documentation for this error.
                type: string
              status:
                description: HTTP status code.
                type: integer
                example: 403
              title:
                description: HTTP status code
                type: string
                example: Bad Request
              instance:
                description: Konnect traceback error code.
                type: string
                example: konnect:trace:3674017986744198214
              detail:
                description: Information about the error response.
                type: string
                example: Only org admins or analytics admins can create reports.
            example:
              status: 403
              type: https://kongapi.info/konnect/permission-denied
              title: Permission denied
              instance: konnect:trace:2822394689570210664
              detail: You do not have sufficient permissions to perform this action.
    TooManyRequests:
      description: Too many requests
      content:
        application/problem+json:
          schema:
            description: The error response object.
            type: object
            properties:
              type:
                description: Documentation for this error.
                type: string
              status:
                description: The HTTP status code.
                type: integer
                example: 429
              title:
                description: The error response code.
                type: string
                example: Too Many Requests
              instance:
                description: The Konnect traceback code
                type: string
                example: konnect:trace:2287285207635123011
              detail:
                description: Details about the error.
                type: string
                example: You have exceeded your rate limit for this time period.  Please wait
                  and try again.
            example:
              status: 429
              type: https://kongapi.info/konnect/too-many-requests
              title: Too Many Requests
              instance: konnect:trace:2287285207635123011
              detail: You have exceeded your rate limit for this time period.  Please wait and
                try again.
  schemas:
    Report:
      type: object
      properties:
        id:
          description: The ID of the report.
          type: string
          format: uuid
          example: 7f9fd312-a987-4628-b4c5-bb4f4fddd5f7
          readOnly: true
        created_at:
          description: An ISO-8601 timestamp representing when the report was created.
          type: string
          format: date-time
          example: 2022-11-04T20:10:06.927Z
          readOnly: true
        updated_at:
          description: An ISO-8601 timestamp representing when the report was last updated.
          type: string
          format: date-time
          example: 2022-11-04T20:10:06.927Z
          readOnly: true
        created_by:
          description: The UUID of the Konnect user that created the report.
          type: string
          format: uuid
          example: 7f9fd312-a987-4628-b4c5-bb4f4fddd5f7
          readOnly: true
        name:
          description: >
            The user-provided name for the report.

            If not provided, the report will be named "Untitled Report" with a
            timestamp suffix.
          type: string
          maxLength: 255
          minLength: 1
        description:
          description: An optional extended description for the report.
          type: string
        chart_type:
          description: Visualization type selected for this report.
          type: string
          default: HORIZONTAL_BAR
          enum:
            - HORIZONTAL_BAR
            - VERTICAL_BAR
            - LINE
        time_range:
          $ref: "#/components/schemas/TimeRange"
        query:
          type: object
          properties:
            metrics:
              description: >
                A property of your API (such as request count or latency) that
                you wish to report on.

                Your chosen metric is aggregated within the specified
                dimensions, meaning that if you query 'request count by
                service', you'll receive the total number of requests each
                service received within the given time frame.  Some metrics,
                such as latency and response size, have more complicated
                aggregations: selecting P99 will result in the 99th percentile
                of the chosen metric.
              type: array
              items:
                type: string
                enum:
                  - REQUEST_COUNT
                  - REQUEST_PER_MINUTE
                  - RESPONSE_LATENCY_P99
                  - RESPONSE_LATENCY_P95
                  - RESPONSE_LATENCY_P50
                  - RESPONSE_SIZE_P99
                  - RESPONSE_SIZE_P95
                  - RESPONSE_SIZE_P50
                  - REQUEST_SIZE_P99
                  - REQUEST_SIZE_P95
                  - REQUEST_SIZE_P50
              default:
                - REQUEST_COUNT
              maxItems: 1
              minItems: 1
            dimensions:
              description: >
                The dimensions for the report.  A report may have up to 2
                dimensions, including time.

                If the report has a timeseries graph, the time dimension will be
                added automatically if not provided.

                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_PRODUCT
                  - API_PRODUCT_VERSION
                  - ROUTE
                  - APPLICATION
                  - STATUS_CODE
                  - STATUS_CODE_GROUPED
                  - GATEWAY_SERVICE
                  - CONTROL_PLANE
                  - TIME
              default: []
              maxItems: 2
            granularity:
              description: >
                `granularity` is only valid for queries that include a time
                dimension, and it specifies the time buckets for the returned
                data.  For example, `MINUTELY` granularity will return
                datapoints for every minute.  Not all granularities are
                available for all time ranges: for example, custom timeframes
                only have `DAILY` granularity.


                If unspecified, a default value for the given time range will be
                chosen according to the following table:


                - `FIFTEEN_MIN`: `MINUTELY`

                - `ONE_HOUR`: `MINUTELY`

                - `SIX_HOUR`: `HOURLY`

                - `TWELVE_HOUR`: `HOURLY`

                - `ONE_DAY`: `HOURLY`

                - `SEVEN_DAY`: `DAILY`

                - `THIRTY_DAY`: `DAILY`

                - `CURRENT_WEEK`: `DAILY`

                - `CURRENT_MONTH`: `DAILY`

                - `PREVIOUS_WEEK`: `DAILY`

                - `PREVIOUS_MONTH`: `DAILY`
              type: string
              enum:
                - MINUTELY
                - HOURLY
                - DAILY
                - WEEKLY
            filter:
              type: array
              items:
                discriminator:
                  propertyName: dimension
                  mapping:
                    API_PRODUCT: "#/components/schemas/ApiProductFilter"
                    API_PRODUCT_VERSION: "#/components/schemas/ApiProductVersionFilter"
                    ROUTE: "#/components/schemas/RouteFilter"
                    APPLICATION: "#/components/schemas/ApplicationFilter"
                    STATUS_CODE: "#/components/schemas/StatusCodeFilter"
                    STATUS_CODE_GROUPED: "#/components/schemas/StatusCodeGroupedFilter"
                    GATEWAY_SERVICE: "#/components/schemas/GatewayServiceFilter"
                    CONTROL_PLANE: "#/components/schemas/ControlPlaneFilter"
                oneOf:
                  - $ref: "#/components/schemas/ApiProductFilter"
                  - $ref: "#/components/schemas/ApiProductVersionFilter"
                  - $ref: "#/components/schemas/RouteFilter"
                  - $ref: "#/components/schemas/ApplicationFilter"
                  - $ref: "#/components/schemas/StatusCodeFilter"
                  - $ref: "#/components/schemas/StatusCodeGroupedFilter"
                  - $ref: "#/components/schemas/GatewayServiceFilter"
                  - $ref: "#/components/schemas/ControlPlaneFilter"
              default: []
      example:
        summary: Bar chart of status codes by API product for the past 24 hours
        description: A vertical bar chart grouping data first by API product, then by
          status code, for the past 24 hours.
        value:
          name: Status codes by service
          chart_type: VERTICAL_BAR
          time_range:
            type: RELATIVE
            time_period: 24H
          query:
            metrics:
              - REQUEST_COUNT
            dimensions:
              - API_PRODUCT
              - STATUS_CODE
    TimeRange:
      description: >
        The period of time to return data.  Relative time ranges are relative to
        the current moment.  Absolute time ranges specify an unchanging period
        of time.  If not specified, a default relative timeframe of last 24
        hours will be chosen.
      default:
        type: RELATIVE
        time_period: 24H
      discriminator:
        propertyName: type
        mapping:
          relative: "#/components/schemas/RelativeTimeRange"
          absolute: "#/components/schemas/AbsoluteTimeRange"
      oneOf:
        - $ref: "#/components/schemas/RelativeTimeRange"
        - $ref: "#/components/schemas/AbsoluteTimeRange"
    ApiProductFilter:
      type: object
      properties:
        dimension:
          description: The dimension to filter.
          type: string
          enum:
            - API_PRODUCT
        type:
          $ref: "#/components/schemas/FilterType"
        values:
          description: |
            The UUIDs of the API products 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}$
      required:
        - dimension
        - type
        - values
    ApiProductVersionFilter:
      type: object
      properties:
        dimension:
          description: The dimension to filter.
          type: string
          enum:
            - API_PRODUCT_VERSION
        type:
          $ref: "#/components/schemas/FilterType"
        values:
          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}$
      required:
        - dimension
        - type
        - values
    RouteFilter:
      type: object
      properties:
        dimension:
          description: The dimension to filter.
          type: string
          enum:
            - ROUTE
        type:
          $ref: "#/components/schemas/FilterType"
        values:
          description: >
            The routes to include in the results.  Because route UUIDs are only
            unique within a given control plane, the filter values must be of
            the form "[control plane UUID]:[route UUID]".
          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}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      required:
        - dimension
        - type
        - values
    ApplicationFilter:
      type: object
      properties:
        dimension:
          description: The dimension to filter.
          type: string
          enum:
            - APPLICATION
        type:
          $ref: "#/components/schemas/FilterType"
        values:
          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}$
      required:
        - dimension
        - type
        - values
    StatusCodeFilter:
      type: object
      properties:
        dimension:
          description: The dimension to filter.
          type: string
          enum:
            - STATUS_CODE
        type:
          $ref: "#/components/schemas/FilterType"
        values:
          description: |
            Only include requests with specific status codes in the results.
          type: array
          items:
            type: integer
            minimum: 100
            maximum: 999
      required:
        - dimension
        - type
        - values
    StatusCodeGroupedFilter:
      type: object
      properties:
        dimension:
          description: The dimension to filter.
          type: string
          enum:
            - STATUS_CODE_GROUPED
        type:
          $ref: "#/components/schemas/FilterType"
        values:
          description: |
            Only include the given groups of status codes in the results.
          type: array
          items:
            type: string
            pattern: ^\d[xX][xX]$
      required:
        - dimension
        - type
        - values
    GatewayServiceFilter:
      type: object
      properties:
        dimension:
          description: The dimension to filter.
          type: string
          enum:
            - GATEWAY_SERVICE
        type:
          $ref: "#/components/schemas/FilterType"
        values:
          description: >
            The gateway services to include in the results.  Because gateway
            service UUIDs are only unique within a given control plane, the
            filter values must be in the form "[control plane UUID]:[service
            UUID]".
          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}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      required:
        - dimension
        - type
        - values
    ControlPlaneFilter:
      type: object
      properties:
        dimension:
          description: The dimension to filter.
          type: string
          enum:
            - CONTROL_PLANE
        type:
          $ref: "#/components/schemas/FilterType"
        values:
          description: |
            The UUIDs of the control planes 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}$
      required:
        - dimension
        - type
        - values
    RelativeTimeRange:
      type: object
      properties:
        type:
          type: string
          enum:
            - RELATIVE
        time_period:
          description: Query data from the specified period relative to now.
          type: string
          enum:
            - 15M
            - 1H
            - 6H
            - 12H
            - 24H
            - 7D
            - 30D
            - CURRENT_WEEK
            - CURRENT_MONTH
            - PREVIOUS_WEEK
            - PREVIOUS_MONTH
      required:
        - type
        - time_period
    AbsoluteTimeRange:
      type: object
      properties:
        type:
          type: string
          enum:
            - ABSOLUTE
        start:
          description: An ISO-8601 date value specifying the lower bound of the time
            range, inclusive.
          type: string
          format: date
          example: 2022-11-04
        end:
          description: An ISO-8601 date value specifying the upper bound of the time
            range, inclusive.
          type: string
          format: date
          example: 2022-11-04
      required:
        - type
        - start
        - end
    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
```
