WakaTime · Schema

Heartbeat

A single coding heartbeat sent from a WakaTime IDE plugin to the WakaTime API v1. Heartbeats are the atomic unit of WakaTime — every dashboard, summary, stat, goal, and leaderboard entry is computed from heartbeats.

Developer ProductivityDeveloper ToolsTime TrackingCoding AnalyticsLeaderboardsIDE PluginsOpen SourcePublic APIs

Properties

Name	Type	Description
id	string	WakaTime-assigned heartbeat identifier (UUID).
user_id	string	WakaTime user identifier owning this heartbeat.
entity	string	File path, domain name, or app name that generated the heartbeat.
type	string	Nature of the entity that emitted the heartbeat.
category	string	Activity category attributed to this heartbeat (auto-detected by the plugin or set by a custom rule).
time	number	Unix epoch seconds (with milliseconds) when the heartbeat was generated.
project	stringnull	Project name (typically the git repo name).
project_root_count	integernull	Distance from the project root in directory levels.
branch	stringnull	Git branch name.
language	stringnull	Programming language detected for the entity.
dependencies	array	Detected package dependencies referenced from the entity.
lines	integernull	Total line count of the file at heartbeat time.
line_additions	integernull	Lines added since last heartbeat.
line_deletions	integernull	Lines deleted since last heartbeat.
lineno	integernull	Cursor line position.
cursorpos	integernull	Cursor column position.
is_write	boolean	Whether the heartbeat was triggered by a write/save action.
machine_name_id	stringnull	Identifier of the machine that emitted the heartbeat.
user_agent_id	stringnull	Identifier of the WakaTime editor user-agent that emitted the heartbeat.
created_at	string	Timestamp when WakaTime received the heartbeat.
modified_at	string

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/wakatime/main/json-schema/wakatime-heartbeat-schema.json",
  "title": "Heartbeat",
  "description": "A single coding heartbeat sent from a WakaTime IDE plugin to the WakaTime API v1. Heartbeats are the atomic unit of WakaTime — every dashboard, summary, stat, goal, and leaderboard entry is computed from heartbeats.",
  "type": "object",
  "required": ["entity", "type", "time"],
  "additionalProperties": false,
  "properties": {
    "id": { "type": "string", "description": "WakaTime-assigned heartbeat identifier (UUID).", "examples": ["5f8a2c7f-8b3a-4c2c-9b3f-1d2c4f5b6a7c"] },
    "user_id": { "type": "string", "description": "WakaTime user identifier owning this heartbeat." },
    "entity": { "type": "string", "description": "File path, domain name, or app name that generated the heartbeat.", "examples": ["/Users/kin/code/wakatime-cli/main.go", "github.com", "Slack"] },
    "type": { "type": "string", "enum": ["file", "domain", "app"], "description": "Nature of the entity that emitted the heartbeat." },
    "category": {
      "type": "string",
      "enum": ["coding", "building", "indexing", "debugging", "browsing", "running tests", "writing tests", "manual testing", "code reviewing", "designing", "communicating", "meeting", "learning", "researching", "writing docs", "ai coding"],
      "description": "Activity category attributed to this heartbeat (auto-detected by the plugin or set by a custom rule)."
    },
    "time": { "type": "number", "description": "Unix epoch seconds (with milliseconds) when the heartbeat was generated.", "examples": [1748600000.123] },
    "project": { "type": ["string", "null"], "description": "Project name (typically the git repo name)." },
    "project_root_count": { "type": ["integer", "null"], "description": "Distance from the project root in directory levels." },
    "branch": { "type": ["string", "null"], "description": "Git branch name." },
    "language": { "type": ["string", "null"], "description": "Programming language detected for the entity." },
    "dependencies": { "type": "array", "items": { "type": "string" }, "description": "Detected package dependencies referenced from the entity." },
    "lines": { "type": ["integer", "null"], "description": "Total line count of the file at heartbeat time." },
    "line_additions": { "type": ["integer", "null"], "description": "Lines added since last heartbeat." },
    "line_deletions": { "type": ["integer", "null"], "description": "Lines deleted since last heartbeat." },
    "lineno": { "type": ["integer", "null"], "description": "Cursor line position." },
    "cursorpos": { "type": ["integer", "null"], "description": "Cursor column position." },
    "is_write": { "type": "boolean", "description": "Whether the heartbeat was triggered by a write/save action." },
    "machine_name_id": { "type": ["string", "null"], "description": "Identifier of the machine that emitted the heartbeat." },
    "user_agent_id": { "type": ["string", "null"], "description": "Identifier of the WakaTime editor user-agent that emitted the heartbeat." },
    "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when WakaTime received the heartbeat." },
    "modified_at": { "type": "string", "format": "date-time" }
  }
}