Keen Query API

openapi: 3.1.0
info:
  title: Keen Query API
  description: >-
    The Keen Query API exposes the analytical query types provided by
    the Keen analytics platform: count, count_unique, sum, average, minimum,
    maximum, median, percentile, select_unique, funnel, and multi_analysis.
    Queries support filters, time frames, intervals, group-by, and time zone
    parameters for flexible multi-dimensional analysis of event data stored
    in Keen event collections.
  version: '3.0'
  contact:
    name: Keen Support
    url: https://keen.io/support
  license:
    name: Proprietary
    url: https://keen.io/terms-of-service
externalDocs:
  description: Keen Query API Documentation
  url: https://keen.io/docs/api/#analyses
servers:
  - url: https://api.keen.io/3.0
    description: Keen production API
tags:
  - name: Queries
    description: Run analytical queries against Keen event collections.
paths:
  /projects/{projectId}/queries/count:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: queryCount
      summary: Keen Run count query
      description: Returns the number of events in a collection that match the supplied parameters.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/count_unique:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: queryCountUnique
      summary: Keen Run count_unique query
      description: Returns the number of distinct values for the specified target property in matching events.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/targetProperty'
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/sum:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: querySum
      summary: Keen Run sum query
      description: Returns the sum of numeric values for the target property across matching events.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/targetProperty'
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/average:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: queryAverage
      summary: Keen Run average query
      description: Returns the arithmetic mean of numeric values for the target property across matching events.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/targetProperty'
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/minimum:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: queryMinimum
      summary: Keen Run minimum query
      description: Returns the minimum numeric value of the target property across matching events.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/targetProperty'
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/maximum:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: queryMaximum
      summary: Keen Run maximum query
      description: Returns the maximum numeric value of the target property across matching events.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/targetProperty'
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/median:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: queryMedian
      summary: Keen Run median query
      description: Returns the median numeric value of the target property across matching events.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/targetProperty'
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/percentile:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: queryPercentile
      summary: Keen Run percentile query
      description: Returns the value at the specified percentile for the target property across matching events.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/targetProperty'
        - name: percentile
          in: query
          required: true
          schema:
            type: number
            minimum: 0
            maximum: 100
          description: Percentile to compute (e.g., 95 for the 95th percentile).
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/select_unique:
    parameters:
      - $ref: '#/components/parameters/projectId'
    get:
      operationId: querySelectUnique
      summary: Keen Run select_unique query
      description: Returns the distinct values of the target property across matching events.
      tags: [Queries]
      parameters:
        - $ref: '#/components/parameters/eventCollectionQ'
        - $ref: '#/components/parameters/targetProperty'
        - $ref: '#/components/parameters/timeframe'
        - $ref: '#/components/parameters/filters'
        - $ref: '#/components/parameters/groupBy'
        - $ref: '#/components/parameters/interval'
        - $ref: '#/components/parameters/timezone'
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/funnel:
    parameters:
      - $ref: '#/components/parameters/projectId'
    post:
      operationId: queryFunnel
      summary: Keen Run funnel query
      description: Analyzes user progression through an ordered sequence of steps, each defined as a query against an event collection.
      tags: [Queries]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [steps]
              properties:
                steps:
                  type: array
                  items:
                    type: object
                    properties:
                      event_collection:
                        type: string
                      actor_property:
                        type: string
                      timeframe:
                        type: string
                      filters:
                        type: array
                        items: { type: object }
      responses:
        '200':
          description: Funnel result with counts per step.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: array
                    items:
                      type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{projectId}/queries/multi_analysis:
    parameters:
      - $ref: '#/components/parameters/projectId'
    post:
      operationId: queryMultiAnalysis
      summary: Keen Run multi_analysis query
      description: Runs multiple analyses on the same event collection in a single request, returning all results in a combined response.
      tags: [Queries]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [event_collection, analyses]
              properties:
                event_collection: { type: string }
                analyses:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      analysis_type: { type: string }
                      target_property: { type: string }
                      percentile: { type: number }
                timeframe: { type: string }
                filters:
                  type: array
                  items: { type: object }
                group_by: { type: string }
                interval: { type: string }
      responses:
        '200':
          $ref: '#/components/responses/QueryResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    projectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
      description: Keen project identifier.
    eventCollectionQ:
      name: event_collection
      in: query
      required: true
      schema:
        type: string
      description: Name of the event collection to query.
    targetProperty:
      name: target_property
      in: query
      required: true
      schema:
        type: string
      description: Property used as the target of the aggregation.
    timeframe:
      name: timeframe
      in: query
      required: true
      schema:
        type: string
      description: Relative or absolute time frame for the query (e.g., this_7_days).
    filters:
      name: filters
      in: query
      required: false
      schema:
        type: string
      description: JSON-encoded array of filter objects to narrow events.
    groupBy:
      name: group_by
      in: query
      required: false
      schema:
        type: string
      description: Property name to group results by.
    interval:
      name: interval
      in: query
      required: false
      schema:
        type: string
      description: Time-based grouping interval (e.g., daily, hourly).
    timezone:
      name: timezone
      in: query
      required: false
      schema:
        type: string
      description: Time zone offset for relative timeframes.
  responses:
    QueryResult:
      description: Query result returned successfully.
      content:
        application/json:
          schema:
            type: object
            properties:
              result:
                description: Result value or grouped/intervalled list of results.
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error_code:
          type: string
        message:
          type: string
  securitySchemes:
    readKey:
      type: apiKey
      in: header
      name: Authorization
      description: Keen Read Key for query access.
security:
  - readKey: []