v23

latestOpenAPI 3.0.1raw.githubusercontent.com2026-08-0127977.1 KB

WakaTime Compatibility

Push heartbeats (WakaTime compatible)

Endpoint used by WakaTime plugins to send heartbeat data to the server. This is the core endpoint for tracking time.

post/api/hackatime/v1/users/{id}/heartbeats

Path parameters

idstring required

User ID or "current" (recommended). The authenticated user is resolved from the API token, not this path segment.

Request body

entitystring

File path or entity being tracked

typestring

Entity type, e.g. "file"

timenumber

Unix timestamp (seconds, float)

projectstring

branchstring

ai_modelstring

ai_sessionstring

ai_subscription_planstring

ai_input_tokensinteger

ai_output_tokensinteger

ai_prompt_lengthinteger

ai_line_changesinteger

human_line_changesinteger

languagestring

is_writeboolean

linenointeger

cursorposinteger

linesinteger

categorystring

created_atstring date_time

dependenciesstring[]

May also be sent as a string

editorstring

line_additionsinteger

line_deletionsinteger

machinestring

operating_systemstring

project_root_countinteger

user_agentstring

pluginstring

Accepted but not persisted

Example request

[
  {
    "entity": "app/models/user.rb",
    "type": "file",
    "time": 1710946200,
    "project": "hackatime",
    "branch": "main",
    "ai_model": "gpt/5.3-codex",
    "ai_session": "session-123",
    "ai_subscription_plan": "pro",
    "ai_input_tokens": 1200,
    "ai_output_tokens": 350,
    "ai_prompt_length": 240,
    "ai_line_changes": 18,
    "human_line_changes": 7,
    "language": "Ruby",
    "is_write": true,
    "lineno": 42,
    "cursorpos": 12,
    "lines": 350,
    "category": "coding",
    "created_at": "2024-03-20T15:30:00Z",
    "dependencies": [
      "rails"
    ],
    "editor": "VS Code",
    "line_additions": 8,
    "line_deletions": 3,
    "machine": "Orpheus-MacBook-Pro",
    "operating_system": "Mac",
    "project_root_count": 4,
    "user_agent": "wakatime/v1.115.2 (darwin-24.6.0) go1.23 vscode/1.96.0",
    "plugin": "vscode/1.96.0 vscode-wakatime/24.6.0"
  }
]

Response

accepted