Umami Realtime API

openapi: 3.2.0
info:
  title: Umami Realtime API
  version: 3.3.1
  license:
    identifier: MIT
    name: MIT
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged Realtime across 2 of this provider''s published API definitions: umami-openapi.json, umami-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{instance}
  description: Self-hosted Umami instance (paths begin with /api). Umami Cloud serves the same API at https://api.umami.is/v1 per docs.umami.is/docs/api.
  variables:
    instance:
      default: your-umami-instance.example.com
tags:
- name: Realtime
paths:
  /api/realtime/{websiteId}:
    get:
      description: Returns recent website activity and visitor data for the real-time view, applying the supplied filters.
      operationId: getRealtime
      parameters:
      - description: ID of the website.
        in: path
        name: websiteId
        required: true
        schema:
          type: string
      - description: IANA time zone used to interpret dates and group results, for example America/New_York.
        in: query
        name: timezone
        required: false
        schema:
          type: string
      - description: 'Time interval used to group results: minute, hour, day, month, or year.'
        in: query
        name: unit
        required: false
        schema:
          type: string
      - description: Filter by page URL path.
        in: query
        name: path
        required: false
        schema:
          type: string
      - description: Filter by referring URL.
        in: query
        name: referrer
        required: false
        schema:
          type: string
      - description: Filter by page title.
        in: query
        name: title
        required: false
        schema:
          type: string
      - description: Filter by page URL query string.
        in: query
        name: query
        required: false
        schema:
          type: string
      - description: Operating system used by the visitor.
        in: query
        name: os
        required: false
        schema:
          type: string
      - description: Browser used by the visitor.
        in: query
        name: browser
        required: false
        schema:
          type: string
      - description: Device category used by the visitor.
        in: query
        name: device
        required: false
        schema:
          type: string
      - description: Country code of the visitor.
        in: query
        name: country
        required: false
        schema:
          type: string
      - description: Region or subdivision of the visitor.
        in: query
        name: region
        required: false
        schema:
          type: string
      - description: City of the visitor.
        in: query
        name: city
        required: false
        schema:
          type: string
      - description: Tag attached to the tracked activity.
        in: query
        name: tag
        required: false
        schema:
          type: string
      - description: Hostname on which the activity occurred.
        in: query
        name: hostname
        required: false
        schema:
          type: string
      - description: Custom identifier assigned to the visitor.
        in: query
        name: distinctId
        required: false
        schema:
          type: string
      - description: Preferred language reported by the visitor browser.
        in: query
        name: language
        required: false
        schema:
          type: string
      - description: Filter by custom event name.
        in: query
        name: event
        required: false
        schema:
          type: string
      - description: UTM campaign source.
        in: query
        name: utmSource
        required: false
        schema:
          type: string
      - description: UTM campaign medium.
        in: query
        name: utmMedium
        required: false
        schema:
          type: string
      - description: UTM campaign name.
        in: query
        name: utmCampaign
        required: false
        schema:
          type: string
      - description: UTM campaign content.
        in: query
        name: utmContent
        required: false
        schema:
          type: string
      - description: UTM campaign search term.
        in: query
        name: utmTerm
        required: false
        schema:
          type: string
      - description: Set a non-empty value to exclude visits with only one pageview.
        in: query
        name: excludeBounce
        required: false
        schema:
          type: string
      - description: ID of a saved segment used to filter results.
        in: query
        name: segment
        required: false
        schema:
          format: uuid
          type: string
      - description: ID of a saved cohort used to filter visitors.
        in: query
        name: cohort
        required: false
        schema:
          format: uuid
          type: string
      - description: 'Event type: 1 for a pageview or 2 for a custom event.'
        in: query
        name: eventType
        required: false
        schema:
          minimum: 1
          type: integer
      - description: Whether records must match all filters or any filter.
        in: query
        name: match
        required: false
        schema:
          enum:
          - all
          - any
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  countries:
                    additionalProperties:
                      type: number
                    properties: {}
                    type: object
                  events:
                    items:
                      properties:
                        __type:
                          anyOf:
                          - const: event
                          - const: session
                          - const: pageview
                        browser:
                          description: Browser used by the visitor.
                          type: string
                        country:
                          description: Country code of the visitor.
                          type: string
                        createdAt:
                          anyOf:
                          - type: string
                          - format: date-time
                            type: string
                          description: Date and time the record was created.
                        device:
                          description: Device category used by the visitor.
                          type: string
                        eventName:
                          description: Name of the custom event.
                          type: string
                        hostname:
                          description: Hostname on which the activity occurred.
                          type: string
                        os:
                          description: Operating system used by the visitor.
                          type: string
                        referrerDomain:
                          description: Domain of the referring page.
                          type: string
                        sessionId:
                          description: ID of the visitor session.
                          type: string
                        urlPath:
                          description: Path portion of the page URL.
                          type: string
                      required:
                      - __type
                      - sessionId
                      - eventName
                      - createdAt
                      - browser
                      - os
                      - device
                      - country
                      - urlPath
                      - referrerDomain
                      - hostname
                      type: object
                    type: array
                  referrers:
                    additionalProperties:
                      type: number
                    properties: {}
                    type: object
                  series:
                    properties:
                      views:
                        description: Pageview counts for the selected period.
                        items:
                          properties:
                            t:
                              type: string
                            x:
                              type: string
                            y:
                              type: number
                          required:
                          - x
                          - t
                          - y
                          type: object
                        type: array
                      visitors:
                        description: Unique visitor counts for the selected period.
                        items:
                          properties:
                            t:
                              type: string
                            x:
                              type: string
                            y:
                              type: number
                          required:
                          - x
                          - t
                          - y
                          type: object
                        type: array
                    required:
                    - views
                    - visitors
                    type: object
                  timestamp:
                    type: number
                  totals:
                    properties:
                      countries:
                        type: number
                      events:
                        type: number
                      views:
                        description: Pageview counts for the selected period.
                        type: number
                      visitors:
                        description: Unique visitor counts for the selected period.
                        type: number
                    required:
                    - views
                    - visitors
                    - events
                    - countries
                    type: object
                  urls:
                    additionalProperties:
                      type: number
                    properties: {}
                    type: object
                required:
                - countries
                - events
                - referrers
                - timestamp
                - series
                - totals
                - urls
                type: object
          description: The operation completed successfully.
        '400':
          content:
            application/json:
              example:
                error:
                  code: bad-request
                  message: Bad request.
                  status: 400
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Bad request.
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Unauthorized.
                  status: 401
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unauthorized.
      security:
      - bearerAuth: []
      - shareContext: []
        shareToken: []
      summary: Get real-time website activity
      tags:
      - Realtime
      x-umami-audience: public
      x-umami-contract: explicit
      x-umami-source: src/app/api/realtime/[websiteId]/contract.generated.ts
components:
  schemas:
    ApiError:
      additionalProperties: false
      description: Standard Umami API error response.
      properties:
        error:
          additionalProperties: {}
          description: Error details returned when the operation fails.
          properties:
            code:
              type: string
            message:
              description: Human-readable explanation of the result.
              type: string
            status:
              maximum: 9007199254740991
              minimum: -9007199254740991
              type: integer
          required:
          - message
          - code
          - status
          type: object
      required:
      - error
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: Token returned by POST /api/auth/login, or an API key (`umami_…`) created under Settings → API keys (self-hosted only).
      scheme: bearer
      type: http
    shareContext:
      description: Required context header when authenticating with a share token.
      in: header
      name: x-umami-share-context
      type: apiKey
    shareToken:
      description: Signed token returned by a share endpoint.
      in: header
      name: x-umami-share-token
      type: apiKey
externalDocs:
  description: Umami API documentation
  url: https://docs.umami.is/docs/api
x-refined-from:
- umami-openapi.json
- umami-openapi.yml