WakaTime Durations API

openapi: 3.2.0
info:
  title: WakaTime Commits Durations API
  version: v1
  description: 'WakaTime API v1 provides automated time-tracking analytics for software developers. IDE

    plugins (VS Code, JetBrains, Vim, Emacs, Sublime, Xcode, Visual Studio, Eclipse, Zed, and

    many more) send "heartbeats" describing the file, project, language, branch, and editor a

    developer is working in. WakaTime aggregates that data into dashboards, summaries, stats,

    goals, leaderboards, and team/org dashboards.


    Authentication is via OAuth 2.0 (authorize / token / revoke) with scopes such as

    `read_summaries`, `read_stats`, `read_goals`, `read_heartbeats`, `write_heartbeats`,

    `read_orgs`, `write_orgs`, and `email`, or via API Key (HTTP Basic auth or `?api_key=`)

    for personal use. The default rate limit is fewer than 10 requests per second on average

    over any 5-minute window.


    All responses follow the pattern `{"data": ...}` for successful requests or

    `{"error": "message"}` for errors.

    '
  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: Durations
  description: Continuous time-on-task spans derived from heartbeats.
paths:
  /users/current/durations:
    get:
      operationId: listDurations
      summary: List Durations
      description: Returns activity durations for a given day, derived from heartbeats.
      tags:
      - Durations
      parameters:
      - $ref: '#/components/parameters/DateQueryRequired'
      - $ref: '#/components/parameters/ProjectQuery'
      - $ref: '#/components/parameters/BranchesQuery'
      - $ref: '#/components/parameters/TimeoutQuery'
      - $ref: '#/components/parameters/WritesOnlyQuery'
      - $ref: '#/components/parameters/TimezoneQuery'
      - $ref: '#/components/parameters/SliceByQuery'
      responses:
        '200':
          description: Durations for the day.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Duration'
              examples:
                ListDurations200Example:
                  summary: Default listDurations 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - time: 1.0
                      duration: 1.0
                      project: wakatime-cli
                      branch: main
                      language: Python
                      category: coding
                      editor: example
                      operating_system: example
                      machine: example
                      color: '#3498db'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    TimeoutQuery:
      name: timeout
      in: query
      description: Keystroke timeout in minutes (defaults to user's account setting).
      schema:
        type: integer
        minimum: 1
        maximum: 60
      example: 1
    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
    DateQueryRequired:
      name: date
      in: query
      required: true
      description: Day to query (YYYY-MM-DD).
      schema:
        type: string
        format: date
      example: '2026-05-30'
    ProjectQuery:
      name: project
      in: query
      description: Filter by project name.
      schema:
        type: string
      example: example
    WritesOnlyQuery:
      name: writes_only
      in: query
      description: Whether to only include time editing (writing) files.
      schema:
        type: boolean
      example: true
    BranchesQuery:
      name: branches
      in: query
      description: Comma-separated list of git branches to include.
      schema:
        type: string
      example: example
    SliceByQuery:
      name: slice_by
      in: query
      description: Slice durations by entity, language, dependencies, os, editor, category, or machine.
      schema:
        type: string
        enum:
        - entity
        - language
        - dependencies
        - os
        - editor
        - category
        - machine
      example: entity
  schemas:
    Duration:
      type: object
      properties:
        time:
          type: number
          format: float
          description: Unix epoch seconds when the duration started.
          example: 1.0
        duration:
          type: number
          format: float
          description: Duration in seconds.
          example: 1.0
        project:
          type:
          - string
          - 'null'
          example: wakatime-cli
        branch:
          type:
          - string
          - 'null'
          example: main
        language:
          type:
          - string
          - 'null'
          example: Python
        category:
          type:
          - string
          - 'null'
          example: coding
        editor:
          type:
          - string
          - 'null'
          example: example
        operating_system:
          type:
          - string
          - 'null'
          example: example
        machine:
          type:
          - string
          - 'null'
          example: example
        color:
          type:
          - string
          - 'null'
          example: '#3498db'
  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_...`.