POST
/v1/users/{user}/heartbeatsCreate a heartbeat
Creates a heartbeat for the specified user. Submit a JSON object with the activity data you want to record, such as entity, language, category, and line-change values. The schema does not mark any heartbeat fields as required.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
userstringrequired
The username to submit the heartbeat for, or `current`.
A single heartbeat object containing activity data.
ai_input_tokensintegeroptional
The number of AI input tokens.
ai_line_changesintegeroptional
The number of line changes attributed to AI.
ai_output_tokensintegeroptional
The number of AI output tokens.
ai_prompt_lengthintegeroptional
The length of the AI prompt.
ai_sessionstringoptional
The identifier of the AI session.
branchstringoptional
The source control branch associated with the activity.
categorystringoptional
The category of activity, such as coding or writing.
created_atnumberoptional
https://gorm.io/docs/conventions.html#CreatedAt
cursorposintegeroptional
The cursor position associated with the activity.
editorstringoptional
ignored because editor might be parsed differently by wakatime
entitystringoptional
The file or other entity associated with the activity.
human_line_changesintegeroptional
The number of line changes attributed to a human.
is_writebooleanoptional
Whether the activity represents a write operation.
languagestringoptional
The programming language associated with the activity.
line_additionsintegeroptional
The number of lines added.
line_deletionsintegeroptional
linenointegeroptional
linesintegeroptional
machinestringoptional
ignored because wakatime api doesn't return machines currently
operating_systemstringoptional
ignored because os might be parsed differently by wakatime
projectstringoptional
project_root_countintegeroptional
timenumberoptional
note: on sqlite, table will have an additional column `time_real`, introduced "manually" by migration 20260111
see https://github.com/muety/wakapi/issues/882 for details
typestringoptional
user_agentstringoptional
201Returns the created heartbeat.
Error handling
The user path parameter must identify a username or be current. The request body must be a JSON object; no heartbeat fields are marked as required.