openapi: 3.0.3
info:
title: WakaTime 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: [email protected]
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
tags:
- name: Users
description: Authenticated user profile and public user lookups.
- name: Heartbeats
description: Coding-activity pings sent by editor plugins.
- name: Durations
description: Continuous time-on-task spans derived from heartbeats.
- name: Summaries
description: Daily aggregations of coding activity by project, language, editor, OS, machine, branch, and category.
- name: Stats
description: User-wide statistics over preset and custom ranges.
- name: Insights
description: Curated analytics views (weekdays, days, projects, languages, editors, machines, operating systems, AI days, best day, daily average).
- name: Projects
description: Projects the authenticated user has logged time against.
- name: Commits
description: Per-project commits enriched with coding time.
- name: Goals
description: User coding goals and their progress.
- name: Custom Rules
description: User and organization custom-rule definitions for time attribution.
- name: External Durations
description: Non-IDE activity durations created via the API.
- name: Data Dumps
description: Full data exports.
- name: Editors
description: Available editor plugins and versions.
- name: Languages
description: Programming languages.
- name: Machines
description: Devices that have sent heartbeats.
- name: User Agents
description: Editor + OS user-agent inventory.
- name: Leaderboards
description: Public and private leaderboard rankings.
- name: Status Bar
description: Cached today-only stats for status-bar displays.
- name: Organizations
description: Team/organization dashboards and member analytics.
- name: Meta
description: WakaTime infrastructure metadata.
- name: OAuth
description: OAuth 2.0 authorization endpoints.
security:
- oauth2: []
- apiKey: []
- bearerAuth: []
paths:
/users/current:
get:
operationId: getCurrentUser
summary: Get Current User
description: Returns the authenticated user's profile.
tags: [Users]
security:
- oauth2: [email]
- apiKey: []
responses:
'200':
description: The authenticated user.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/User'
examples:
GetCurrentUser200Example:
summary: Default getCurrentUser 200 response
x-microcks-default: true
value:
data:
id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
username: kinlane
display_name: Kin Lane
full_name: Kin Lane
email: [email protected]
photo: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
photo_public: true
is_email_public: true
is_email_confirmed: true
timezone: America/Los_Angeles
last_heartbeat_at: '2026-05-30T12:34:56Z'
last_plugin: vscode-wakatime/24.0.0 vscode-wakatime/24.0.0
last_plugin_name: vscode
last_project: wakatime-cli
plan: free
bio: Founder of API Evangelist.
location: Hermosa Beach, CA
languages_used_public: true
logged_time_public: true
website: https://wakatime.com
human_readable_website: wakatime.com
wonderfuldev_username: kinlane
github_username: kinlane
twitter_username: kinlane
linkedin_username: kinlane
created_at: '2026-05-30T12:34:56Z'
modified_at: '2026-05-30T12:34:56Z'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/{user}:
get:
operationId: getUser
summary: Get User
description: Returns the public profile for the given user.
tags: [Users]
parameters:
- $ref: '#/components/parameters/UserPath'
responses:
'200':
description: The requested user's public profile.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/PublicUser'
examples:
GetUser200Example:
summary: Default getUser 200 response
x-microcks-default: true
value:
data:
id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
username: kinlane
display_name: Kin Lane
full_name: Kin Lane
email: [email protected]
photo: https://wakatime.com/photo/5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
photo_public: true
is_email_public: true
is_email_confirmed: true
timezone: America/Los_Angeles
last_heartbeat_at: '2026-05-30T12:34:56Z'
last_plugin: vscode-wakatime/24.0.0 vscode-wakatime/24.0.0
last_plugin_name: vscode
last_project: wakatime-cli
plan: free
bio: Founder of API Evangelist.
location: Hermosa Beach, CA
languages_used_public: true
logged_time_public: true
website: https://wakatime.com
human_readable_website: wakatime.com
wonderfuldev_username: kinlane
github_username: kinlane
twitter_username: kinlane
linkedin_username: kinlane
created_at: '2026-05-30T12:34:56Z'
modified_at: '2026-05-30T12:34:56Z'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/current/all_time_since_today:
get:
operationId: getAllTimeSinceTodayCurrent
summary: Get All Time Since Today
description: Returns the total coding activity the authenticated user has logged since the account was created, up to today.
tags: [Stats]
parameters:
- $ref: '#/components/parameters/ProjectQuery'
responses:
'200':
description: All-time-since-today totals.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AllTimeSinceToday'
examples:
GetAllTimeSinceTodayCurrent200Example:
summary: Default getAllTimeSinceTodayCurrent 200 response
x-microcks-default: true
value:
data:
total_seconds: 4
text: "1,234 hrs 5 mins"
decimal: "1234.08"
digital: "1234:05"
is_up_to_date: '2026-05-30T12:34:56Z'
percent_calculated: 1
range: &id001 {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/{user}/all_time_since_today:
get:
operationId: getAllTimeSinceToday
summary: Get User All Time Since Today
description: Returns the all-time-since-today totals for a specific user (requires scope on that user's data).
tags: [Stats]
parameters:
- $ref: '#/components/parameters/UserPath'
- $ref: '#/components/parameters/ProjectQuery'
responses:
'200':
description: All-time-since-today totals for the user.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/AllTimeSinceToday'
examples:
GetAllTimeSinceToday200Example:
summary: Default getAllTimeSinceToday 200 response
x-microcks-default: true
value:
data:
total_seconds: 4
text: "1,234 hrs 5 mins"
decimal: "1234.08"
digital: "1234:05"
is_up_to_date: '2026-05-30T12:34:56Z'
percent_calculated: 1
range: *id001
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/current/heartbeats:
get:
operationId: listHeartbeats
summary: List Heartbeats
description: Returns the authenticated user's heartbeats for a given day.
tags: [Heartbeats]
parameters:
- $ref: '#/components/parameters/DateQueryRequired'
responses:
'200':
description: A list of heartbeats for the day.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Heartbeat'
examples:
ListHeartbeats200Example:
summary: Default listHeartbeats 200 response
x-microcks-default: true
value:
data:
- entity: /Users/kin/code/wakatime-cli/main.go
type: file
category: coding
time: 1.0
project: wakatime-cli
project_root_count: 4
branch: main
language: Python
dependencies: &id002
- example
lines: 1
line_additions: 1
line_deletions: 1
lineno: 1
cursorpos: 1
is_write: true
id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
user_id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
created_at: '2026-05-30T12:34:56Z'
modified_at: '2026-05-30T12:34:56Z'
machine_name_id: machine-001
user_agent_id: ua-001
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createHeartbeat
summary: Create Heartbeat
description: Creates a single heartbeat from an editor plugin.
tags: [Heartbeats]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HeartbeatInput'
examples:
CreateHeartbeatRequestExample:
summary: Default createHeartbeat request
x-microcks-default: true
value:
entity: /Users/kin/code/wakatime-cli/main.go
type: file
category: coding
time: 1.0
project: wakatime-cli
project_root_count: 4
branch: main
language: Python
dependencies: *id002
lines: 1
line_additions: 1
line_deletions: 1
lineno: 1
cursorpos: 1
is_write: true
responses:
'201':
description: The created heartbeat.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Heartbeat'
examples:
CreateHeartbeat201Example:
summary: Default createHeartbeat 201 response
x-microcks-default: true
value:
data:
entity: /Users/kin/code/wakatime-cli/main.go
type: file
category: coding
time: 1.0
project: wakatime-cli
project_root_count: 4
branch: main
language: Python
dependencies: *id002
lines: 1
line_additions: 1
line_deletions: 1
lineno: 1
cursorpos: 1
is_write: true
id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
user_id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
created_at: '2026-05-30T12:34:56Z'
modified_at: '2026-05-30T12:34:56Z'
machine_name_id: machine-001
user_agent_id: ua-001
'202':
description: Heartbeat accepted for asynchronous processing.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/current/heartbeats.bulk:
post:
operationId: createHeartbeatsBulk
summary: Create Heartbeats Bulk
description: Creates multiple heartbeats in a single request (up to 25).
tags: [Heartbeats]
requestBody:
required: true
content:
application/json:
schema:
type: array
maxItems: 25
items:
$ref: '#/components/schemas/HeartbeatInput'
examples:
CreateHeartbeatsBulkRequestExample:
summary: Default createHeartbeatsBulk request
x-microcks-default: true
value:
- entity: /Users/kin/code/wakatime-cli/main.go
type: file
category: coding
time: 1.0
project: wakatime-cli
project_root_count: 4
branch: main
language: Python
dependencies: *id002
lines: 1
line_additions: 1
line_deletions: 1
lineno: 1
cursorpos: 1
is_write: true
responses:
'201':
description: The created heartbeats and per-item statuses.
content:
application/json:
schema:
type: object
properties:
responses:
type: array
items:
type: array
description: "Tuple of [body, status_code] per submitted heartbeat."
examples:
CreateHeartbeatsBulk201Example:
summary: Default createHeartbeatsBulk 201 response
x-microcks-default: true
value:
responses:
- - example
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteHeartbeatsBulk
summary: Delete Heartbeats Bulk
description: Deletes multiple heartbeats by date and id in a single request.
tags: [Heartbeats]
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
required: [id, date]
properties:
id:
type: string
date:
type: string
format: date
examples:
DeleteHeartbeatsBulkRequestExample:
summary: Default deleteHeartbeatsBulk request
x-microcks-default: true
value:
- id: example
date: '2026-05-30'
responses:
'200':
description: Bulk delete results.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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
/users/current/external_durations:
get:
operationId: listExternalDurations
summary: List External Durations
description: Returns external (non-editor) durations for a given day.
tags: [External Durations]
parameters:
- $ref: '#/components/parameters/DateQueryRequired'
- $ref: '#/components/parameters/ProjectQuery'
- $ref: '#/components/parameters/TimezoneQuery'
responses:
'200':
description: External durations for the day.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ExternalDuration'
examples:
ListExternalDurations200Example:
summary: Default listExternalDurations 200 response
x-microcks-default: true
value:
data:
- external_id: ext-001
entity: /Users/kin/code/wakatime-cli/main.go
type: file
category: coding
start_time: 1.0
end_time: 1.0
project: wakatime-cli
branch: main
language: Python
meta: &id003 {}
id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
user_id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
created_at: '2026-05-30T12:34:56Z'
modified_at: '2026-05-30T12:34:56Z'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createExternalDuration
summary: Create External Duration
description: Creates a single external duration (for non-editor activity such as meetings, design tools, etc.).
tags: [External Durations]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalDurationInput'
examples:
CreateExternalDurationRequestExample:
summary: Default createExternalDuration request
x-microcks-default: true
value:
external_id: ext-001
entity: /Users/kin/code/wakatime-cli/main.go
type: file
category: coding
start_time: 1.0
end_time: 1.0
project: wakatime-cli
branch: main
language: Python
meta: *id003
responses:
'201':
description: The created external duration.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/current/external_durations.bulk:
post:
operationId: createExternalDurationsBulk
summary: Create External Durations Bulk
description: Creates multiple external durations in a single request (up to 1,000).
tags: [External Durations]
requestBody:
required: true
content:
application/json:
schema:
type: array
maxItems: 1000
items:
$ref: '#/components/schemas/ExternalDurationInput'
examples:
CreateExternalDurationsBulkRequestExample:
summary: Default createExternalDurationsBulk request
x-microcks-default: true
value:
- external_id: ext-001
entity: /Users/kin/code/wakatime-cli/main.go
type: file
category: coding
start_time: 1.0
end_time: 1.0
project: wakatime-cli
branch: main
language: Python
meta: *id003
responses:
'201':
description: Bulk creation results.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteExternalDurationsBulk
summary: Delete External Durations Bulk
description: Deletes multiple external durations by id and date.
tags: [External Durations]
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
required: [id]
properties:
id:
type: string
date:
type: string
format: date
examples:
DeleteExternalDurationsBulkRequestExample:
summary: Default deleteExternalDurationsBulk request
x-microcks-default: true
value:
- id: example
date: '2026-05-30'
responses:
'200':
description: Bulk delete results.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/current/summaries:
get:
operationId: listSummaries
summary: List Summaries
description: Returns daily summaries of coding activity between a start and end date, broken down by project, language, editor, OS, machine, branch, category, and dependencies.
tags: [Summaries]
parameters:
- name: start
in: query
required: true
description: Start date (YYYY-MM-DD) inclusive.
schema: {type: string, format: date}
example: '2026-05-30'
- name: end
in: query
required: true
description: End date (YYYY-MM-DD) inclusive.
schema: {type: string, format: date}
example: '2026-05-30'
- $ref: '#/components/parameters/ProjectQuery'
- $ref: '#/components/parameters/BranchesQuery'
- $ref: '#/components/parameters/TimeoutQuery'
- $ref: '#/components/parameters/WritesOnlyQuery'
- $ref: '#/components/parameters/TimezoneQuery'
- $ref: '#/components/parameters/RangeQuery'
responses:
'200':
description: Daily summaries.
content:
application/json:
schema:
$ref: '#/components/schemas/SummariesResponse'
examples:
ListSummaries200Example:
summary: Default listSummaries 200 response
x-microcks-default: true
value:
data: &id023 []
cumulative_total: &id024 {}
daily_average: &id025 {}
start: '2026-05-30'
end: '2026-05-30'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/current/stats:
get:
operationId: getStatsForRange
summary: Get Stats For Range
description: Returns coding stats for the authenticated user over a date range. May return 202 while WakaTime is calculating the stats.
tags: [Stats]
parameters:
- $ref: '#/components/parameters/RangeQuery'
- $ref: '#/components/parameters/TimeoutQuery'
- $ref: '#/components/parameters/WritesOnlyQuery'
- $ref: '#/components/parameters/TimezoneQuery'
- $ref: '#/components/parameters/ProjectQuery'
responses:
'200':
description: Stats payload.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Stats'
examples:
GetStatsForRange200Example:
summary: Default getStatsForRange 200 response
x-microcks-default: true
value:
data:
id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
user_id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
username: kinlane
range: example
start: '2026-05-30T12:34:56Z'
end: '2026-05-30T12:34:56Z'
days_including_holidays: 1
days_minus_holidays: 1
holidays: 1
status: ok
is_up_to_date: '2026-05-30T12:34:56Z'
percent_calculated: 1
timeout: 1
writes_only: true
timezone: America/Los_Angeles
total_seconds: 4
total_seconds_including_other_language: 1.0
daily_average: 1.0
daily_average_including_other_language: 1.0
human_readable_total: 4 hrs 12 mins
human_readable_daily_average: 3 hrs 30 mins
best_day: &id004 {}
languages: &id005 []
projects: &id006 []
editors: &id007 []
operating_systems: &id008 []
machines: &id009 []
categories: &id010 []
dependencies: &id011 []
created_at: '2026-05-30T12:34:56Z'
modified_at: '2026-05-30T12:34:56Z'
'202':
description: Stats are still being calculated.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/current/stats/{range}:
get:
operationId: getStatsByRange
summary: Get Stats By Named Range
description: Returns coding stats for a preset named range (last_7_days, last_30_days, last_6_months, last_year, all_time).
tags: [Stats]
parameters:
- name: range
in: path
required: true
description: Preset range.
schema:
type: string
enum: [last_7_days, last_30_days, last_6_months, last_year, all_time]
example: last_7_days
responses:
'200':
description: Stats payload.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Stats'
examples:
GetStatsByRange200Example:
summary: Default getStatsByRange 200 response
x-microcks-default: true
value:
data:
id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
user_id: 5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c
username: kinlane
range: example
start: '2026-05-30T12:34:56Z'
end: '2026-05-30T12:34:56Z'
days_including_holidays: 1
days_minus_holidays: 1
holidays: 1
status: ok
is_up_to_date: '2026-05-30T12:34:56Z'
percent_calculated: 1
timeout: 1
writes_only: true
timezone: America/Los_Angeles
total_seconds: 4
total_seconds_including_other_language: 1.0
daily_average: 1.0
daily_average_including_other_language: 1.0
human_readable_total: 4 hrs 12 mins
human_readable_daily_average: 3 hrs 30 mins
best_day: *id004
languages: *id005
projects: *id006
editors: *id007
operating_systems: *id008
machines: *id009
categories: *id010
dependencies: *id011
created_at: '2026-05-30T12:34:56Z'
modified_at: '2026-05-30T12:34:56Z'
'202':
description: Stats are still being calculated.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/users/current/stats_aggregated:
get:
operationId: getStatsAggregated
summary: Get Stats Aggregated
description: Returns aggregated coding stats across all WakaTime users.
tags: [Stats]
parameters:
- $ref: '#/components/parameters/RangeQuery'
responses:
'200':
description: Aggregated stats.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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, lang
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wakatime/refs/heads/main/openapi/wakatime-api-v1-openapi.yml