WakaTime Insights API

openapi: 3.2.0
info:
  title: WakaTime Insights API
  version: v1
  description: WakaTime API v1 provides automated time-tracking analytics for software developers.
  contact:
    name: WakaTime Support
    url: https://wakatime.com/contact
    email: support@wakatime.com
  termsOfService: https://wakatime.com/terms
  license:
    name: WakaTime Terms of Service
    url: https://wakatime.com/terms
  x-generated-from: documentation
  x-source-url: https://wakatime.com/developers
  x-last-validated: '2026-05-30'
servers:
- url: https://wakatime.com/api/v1
  description: WakaTime production API
- url: https://api.wakatime.com/api/v1
  description: WakaTime alternate hostname
security:
- oauth2: []
- apiKey: []
- bearerAuth: []
tags:
- name: Insights
  description: Curated analytics views (weekdays, days, projects, languages, editors, machines, operating systems, AI days, best day, daily average).
paths:
  /users/current/insights/{insight_type}/{range}:
    get:
      operationId: getInsight
      summary: Get Insight
      description: Returns an insight slice for a given type and range.
      tags:
      - Insights
      parameters:
      - name: insight_type
        in: path
        required: true
        description: The insight type.
        schema:
          type: string
          enum:
          - stats
          - weekdays
          - days
          - ai_days
          - best_day
          - daily_average
          - projects
          - languages
          - editors
          - categories
          - machines
          - operating_systems
        example: stats
      - name: range
        in: path
        required: true
        description: The range for the insight (e.g. last_7_days, last_year).
        schema:
          type: string
        example: example
      - $ref: '#/components/parameters/TimezoneQuery'
      - $ref: '#/components/parameters/WritesOnlyQuery'
      responses:
        '200':
          description: Insight payload.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    TimezoneQuery:
      name: timezone
      in: query
      description: Timezone to use (defaults to the user's profile timezone).
      schema:
        type: string
        example: America/Los_Angeles
      example: America/Los_Angeles
    WritesOnlyQuery:
      name: writes_only
      in: query
      description: Whether to only include time editing (writing) files.
      schema:
        type: boolean
      example: true
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow.
      flows:
        authorizationCode:
          authorizationUrl: https://wakatime.com/oauth/authorize
          tokenUrl: https://wakatime.com/oauth/token
          refreshUrl: https://wakatime.com/oauth/token
          scopes:
            email: Read user email.
            read_summaries: Read coding-activity summaries.
            read_stats: Read aggregate stats.
            read_goals: Read coding goals.
            read_heartbeats: Read raw heartbeats.
            write_heartbeats: Send heartbeats.
            read_orgs: Read organization data.
            write_orgs: Modify organization data.
        implicit:
          authorizationUrl: https://wakatime.com/oauth/authorize
          scopes:
            email: Read user email.
            read_summaries: Read coding-activity summaries.
            read_stats: Read aggregate stats.
            read_goals: Read coding goals.
            read_heartbeats: Read raw heartbeats.
            write_heartbeats: Send heartbeats.
            read_orgs: Read organization data.
            write_orgs: Modify organization data.
    apiKey:
      type: http
      scheme: basic
      description: HTTP Basic with the WakaTime API key as the username. Alternatively, pass `?api_key=...` as a query parameter.
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth access token in the Authorization header as `Bearer waka_tok_...`.