WakaTime API

https://wakatime.com/developers
Admin
The WakaTime API provides a programmatic interface for developers to access and manage their coding...
Tokens:77,637
Snippets:207
Trust Score:9.9
Update:1 day ago
Show doc for...
Tokens:
Raw
### GET /api/v1/users/:user/orgs/:org/custom_rules - Example Response

Source: https://wakatime.com/developers

Example 200 response for listing custom rules. The data array contains rule objects with action, source, operation, source_value, destinations, and priority fields.

```json
{
  "data": [
    {
      "action": <string: either "change" or "delete">,
      "source": <string: the heartbeat property to match against source_value>,
      "operation": <string: one of "equals", "contains", "starts with", or "ends with">,
      "source_value": <string: the match string>,
      "destinations": [
        {
          "id": <string: unique id of this custom rule destination>,
          "destination": <string: the heartbeat property to replace with destination_value>,
          "destination_value": <string: the replacement string>,
        }, …
      ],
      "priority": <integer: a unique number determining the order this rule is executed on heartbeats; starts with 1; lower priorities are executed before higher priorities>,
    }, …
  ],
}
```

--------------------------------

### GET /api/v1/meta

Source: https://wakatime.com/developers

Retrieves metadata about the API.

```APIDOC
## GET /api/v1/meta

### Description
Returns metadata about the API, such as version and supported features.

### Method
GET

### Endpoint
/api/v1/meta

### Response
#### Success Response (200)
- **data** (object) - Metadata object.

#### Response Example
{
  "data": {
    "version": "v1",
    "features": ["heartbeats", "summaries"]
  }
}
```

--------------------------------

### GET /api/v1/users/current/projects

Source: https://wakatime.com/developers

Retrieves projects for the current user.

```APIDOC
## GET /api/v1/users/current/projects

### Description
Returns a list of projects for the current user.

### Method
GET

### Endpoint
/api/v1/users/current/projects

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.

### Response
#### Success Response (200)
- **data** (array) - List of project objects.

#### Response Example
{
  "data": [
    {
      "name": "my-project",
      "total_seconds": 12345.67
    }
  ]
}
```

--------------------------------

### GET /api/v1/users/current/summaries

Source: https://wakatime.com/developers

Retrieves summaries for the current user.

```APIDOC
## GET /api/v1/users/current/summaries

### Description
Returns coding summaries for the current user.

### Method
GET

### Endpoint
/api/v1/users/current/summaries

### Parameters
#### Query Parameters
- **start** (string) - Required - Start date (YYYY-MM-DD).
- **end** (string) - Required - End date (YYYY-MM-DD).
- **project** (string) - Optional - Filter by project.

### Response
#### Success Response (200)
- **data** (array) - List of summary objects.

#### Response Example
{
  "data": [
    {
      "date": "2023-01-01",
      "total_seconds": 3600
    }
  ]
}
```

--------------------------------

### GET /api/v1/users/current/projects

Source: https://wakatime.com/developers

Lists WakaTime projects for the current authenticated user. Requires the read_stats.projects scope.

```APIDOC
## GET /api/v1/users/current/projects

### Description
List of WakaTime projects for the current user.

### Method
GET

### Endpoint
/api/v1/users/current/projects

### Parameters
#### Query Parameters
- **q** (String) - Optional - Filter project names by a search term.

### Scope Required
read_stats.projects

### Response
#### Success Response (200)
- **data** (array) - List of project objects.
  - **id** (string) - Unique project id.
  - **name** (string) - Project name.
  - **repository** (string) - Associated repository if connected.
  - **badge** (string) - Associated project badge if enabled.
  - **color** (string) - Custom project color as hex string, or null if using default color.
  - **clients** (list) - Clients associated with this project.
  - **has_public_url** (boolean) - Whether this project has a shareable url defined.
  - **human_readable_last_heartbeat_at** (string) - Time when project last received code stats as human readable string.
  - **last_heartbeat_at** (string) - Time when project last received code stats in ISO 8601 format.
  - **human_readable_first_heartbeat_at** (string) - Time when project first received code stats as human readable string; currently only set for users who signed up after 2024-02-05T00:00:00Z UTC.
  - **first_heartbeat_at** (string) - Time when project first received code stats in ISO 8601 format; currently only set for users who signed up after 2024-02-05T00:00:00Z UTC.
  - **url** (string) - Url of this project relative to wakatime.com.
  - **urlencoded_name** (string) - Project name url entity encoded.
  - **created_at** (string) - Time when project was created in ISO 8601 format.

#### Response Example
```
{
  "data": [
    {
      "id": <string: unique project id>,
      "name": <string: project name>,
      "repository": <string: associated repository if connected>,
      "badge": <string: associated project badge if enabled>,
      "color": <string: custom project color as hex string, or null if using default color>,
      "clients": <list: clients associated with this project>,
      "has_public_url": <boolean: whether this project has a shareable url defined>,
      "human_readable_last_heartbeat_at": <string: time when project last received code stats as human readable string>,
      "last_heartbeat_at": <string: time when project last received code stats in ISO 8601 format>,
      "human_readable_first_heartbeat_at": <string: time when project first received code stats as human readable string; currently only set for users who signed up after 2024-02-05T00:00:00Z UTC>,
      "first_heartbeat_at": <string: time when project first received code stats in ISO 8601 format; currently only set for users who signed up after 2024-02-05T00:00:00Z UTC>,
      "url": <string: url of this project relative to wakatime.com>,
      "urlencoded_name": <string: project name url entity encoded>,
      "created_at": <string: time when project was created in ISO 8601 format>,
    }, …
  ],
}
```
```

--------------------------------

### GET /api/v1/program_languages

Source: https://wakatime.com/developers

Lists all verified program languages supported by WakaTime. No parameters are required.

```APIDOC
## GET /api/v1/program_languages

### Description
List of all verified program languages supported by WakaTime.

### Method
GET

### Endpoint
/api/v1/program_languages

### Response
#### Success Response (200)
- **data** (array) - List of language objects.
  - **id** (string) - Unique id of this language.
  - **name** (string) - Human readable name of this language.
  - **color** (string) - Hex color code, used when displaying this language on WakaTime charts.
  - **is_verified** (boolean) - Whether this language is verified, by GitHub’s linguist or manually by WakaTime admins.
  - **created_at** (string) - Time when this language was created in ISO 8601 format.
  - **modified_at** (string) - Time when this language was last modified in ISO 8601 format.
- **total** (integer) - Number of program languages.
- **total_pages** (integer) - Number of pages.

#### Response Example
```
{
  "data": [
    "id": <string: unique id of this language>,
    "name": <string: human readable name of this language>,
    "color": <string: hex color code, used when displaying this language on WakaTime charts>,
    "is_verified": <boolean: whether this language is verified, by GitHub’s linguist or manually by WakaTime admins>,
    "created_at": <string: time when this language was created in ISO 8601 format>,
    "modified_at": <string: time when this language was last modified in ISO 8601 format>
  ], …
  "total": <integer: number of program languages>,
  "total_pages": <integer: number of pages>,
}
```
```

--------------------------------

### GET /api/v1/users/current/goals

Source: https://wakatime.com/developers

Lists the goals of the currently authenticated user. Requires the read_goals scope.

```APIDOC
## GET /api/v1/users/current/goals

### Description
List a user's goals.

### Method
GET

### Endpoint
/api/v1/users/current/goals

### Parameters
None

### Scope Required
read_goals

### Response
#### Success Response (200)
Returns a list of goals for the current user.

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /api/v1/users/:user/goals

Source: https://wakatime.com/developers

Lists the goals of a specified user. Requires the read_goals scope.

```APIDOC
## GET /api/v1/users/:user/goals

### Description
List a user's goals.

### Method
GET

### Endpoint
/api/v1/users/:user/goals

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or user ID of the user whose goals to list.

### Scope Required
read_goals

### Response
#### Success Response (200)
Returns a list of goals for the specified user.

#### Response Example
(No example provided in source)
```

--------------------------------

### GET /api/v1/users/:user/data_dumps

Source: https://wakatime.com/developers

Lists data exports for the user. Requires the read_heartbeats scope.

```APIDOC
## GET /api/v1/users/:user/data_dumps

### Description
List data exports for the user. A data export can also be created at https://wakatime.com/settings, and contains all the user's code stats as daily Summaries in JSON format since the user's account was created.

### Method
GET

### Endpoint
/api/v1/users/:user/data_dumps

### Scope Required
read_heartbeats

### Response
#### Success Response (200)
- **data** (array) - List of data export objects.
  - **id** (string) - Unique id of this data export.
  - **status** (string) - One of 'Pending…', 'Processing coding activity…', 'Uploading…', or 'Completed'.
  - **percent_complete** (float) - Percent of code stats that have been exported.
  - **download_url** (string) - When completed, the url to download this data export.
  - **type** (string) - Either 'heartbeats' or 'daily'.
  - **is_processing** (boolean) - Whether this data export is currently processing in the background.
  - **is_stuck** (boolean) - Whether this data export is taking too long, probably due to an error.
  - **has_failed** (boolean) - Whether this data export failed to complete due to an error.
  - **expires** (string) - Datetime when this data export can no longer be downloaded.
  - **created_at** (string) - Datetime when this data export was requested.

#### Response Example
{
  "data": [
    {
      "id": "export123",
      "status": "Completed",
      "percent_complete": 100.0,
      "download_url": "https://example.com/download",
      "type": "daily",
      "is_processing": false,
      "is_stuck": false,
      "has_failed": false,
      "expires": "2023-01-01T00:00:00Z",
      "created_at": "2023-01-01T00:00:00Z"
    }
  ]
}
```

--------------------------------

### Authorization Header Example

Source: https://wakatime.com/developers

Shows how to include an OAuth 2.0 access token in the Authorization header for API requests. Replace waka_tok_12345 with the actual token.

```http
Authorization: Bearer waka_tok_12345
```

--------------------------------

### PUT /api/v1/users/:user/orgs/:org/custom_rules - Example Response

Source: https://wakatime.com/developers

Example 200 response after updating custom rules. The data object contains a changes object with added, removed, and rearranged arrays.

```json
{
  "data": {
    "changes": {
      "added": [],
      "removed": [],
      "rearranged": [],
    }
  }
}
```

--------------------------------

### HTTP Basic Auth header with API key

Source: https://wakatime.com/developers

Example of an Authorization header using HTTP Basic Auth with a base64-encoded API key. For an API key of '12345', the header is 'Authorization: Basic MTIzNDU='.

```http
Authorization: Basic MTIzNDU=
```

--------------------------------

### GET /api/v1/users/:user/projects

Source: https://wakatime.com/developers

Lists WakaTime projects for a specific user. Requires the read_stats.projects scope.

```APIDOC
## GET /api/v1/users/:user/projects

### Description
List of WakaTime projects for the current user.

### Method
GET

### Endpoint
/api/v1/users/:user/projects

### Parameters
#### Query Parameters
- **q** (String) - Optional - Filter project names by a search term.

### Scope Required
read_stats.projects

### Response
#### Success Response (200)
- **data** (array) - List of project objects.
  - **id** (string) - Unique project id.
  - **name** (string) - Project name.
  - **repository** (string) - Associated repository if connected.
  - **badge** (string) - Associated project badge if enabled.
  - **color** (string) - Custom project color as hex string, or null if using default color.
  - **clients** (list) - Clients associated with this project.
  - **has_public_url** (boolean) - Whether this project has a shareable url defined.
  - **human_readable_last_heartbeat_at** (string) - Time when project last received code stats as human readable string.
  - **last_heartbeat_at** (string) - Time when project last received code stats in ISO 8601 format.
  - **human_readable_first_heartbeat_at** (string) - Time when project first received code stats as human readable string; currently only set for users who signed up after 2024-02-05T00:00:00Z UTC.
  - **first_heartbeat_at** (string) - Time when project first received code stats in ISO 8601 format; currently only set for users who signed up after 2024-02-05T00:00:00Z UTC.
  - **url** (string) - Url of this project relative to wakatime.com.
  - **urlencoded_name** (string) - Project name url entity encoded.
  - **created_at** (string) - Time when project was created in ISO 8601 format.

#### Response Example
```
{
  "data": [
    {
      "id": <string: unique project id>,
      "name": <string: project name>,
      "repository": <string: associated repository if connected>,
      "badge": <string: associated project badge if enabled>,
      "color": <string: custom project color as hex string, or null if using default color>,
      "clients": <list: clients associated with this project>,
      "has_public_url": <boolean: whether this project has a shareable url defined>,
      "human_readable_last_heartbeat_at": <string: time when project last received code stats as human readable string>,
      "last_heartbeat_at": <string: time when project last received code stats in ISO 8601 format>,
      "human_readable_first_heartbeat_at": <string: time when project first received code stats as human readable string; currently only set for users who signed up after 2024-02-05T00:00:00Z UTC>,
      "first_heartbeat_at": <string: time when project first received code stats in ISO 8601 format; currently only set for users who signed up after 2024-02-05T00:00:00Z UTC>,
      "url": <string: url of this project relative to wakatime.com>,
      "urlencoded_name": <string: project name url entity encoded>,
      "created_at": <string: time when project was created in ISO 8601 format>,
    }, …
  ],
}
```
```

--------------------------------

### GET /api/v1/leaders

Source: https://wakatime.com/developers

Retrieves leaderboard data.

```APIDOC
## GET /api/v1/leaders

### Description
Returns leaderboard data for public users.

### Method
GET

### Endpoint
/api/v1/leaders

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.

### Response
#### Success Response (200)
- **data** (array) - List of leaderboard entries.

#### Response Example
{
  "data": [
    {
      "user": "username",
      "total_seconds": 12345.67
    }
  ]
}
```

--------------------------------

### Refresh access token using refresh_token (Python)

Source: https://wakatime.com/developers

Shows how to obtain a new access_token when the previous one expires. Uses the refresh_token from the initial OAuth response and posts to the token endpoint. Includes a commented alternative using the rauth library.

```python
import requests

refresh_token = service.access_token_response.json()['refresh_token']

data = {
    'grant_type': 'refresh_token',
    'client_id': client_id,
    'client_secret': client_secret,
    'refresh_token': refresh_token,
}
resp = requests.post('https://wakatime.com/oauth/token', data=data, timeout=5)
print(resp.json())
# Or, using the rauth library:
# session = service.get_auth_session(decoder=json.loads, data=data)
```

--------------------------------

### GET /api/v1/users/current/stats

Source: https://wakatime.com/developers

Retrieves stats for the current user.

```APIDOC
## GET /api/v1/users/current/stats

### Description
Returns coding stats for the current user.

### Method
GET

### Endpoint
/api/v1/users/current/stats

### Parameters
#### Query Parameters
- **range** (string) - Optional - Time range (e.g., last_7_days).

### Response
#### Success Response (200)
- **data** (object) - Stats object.

#### Response Example
{
  "data": {
    "total_seconds": 12345.67,
    "languages": [
      {
        "name": "Python",
        "total_seconds": 12345.67
      }
    ]
  }
}
```

--------------------------------

### POST /api/v1/users/:user/heartbeats

Source: https://wakatime.com/developers

Creates a heartbeat representing activity for a user. Editor and OS are detected from the User-Agent header. Normally you don't need this endpoint and should use wakatime-cli to send heartbeats.

```APIDOC
## POST /api/v1/users/:user/heartbeats

### Description
Creates a heartbeat representing activity for a user. Editor and OS are detected from the User-Agent header. Normally you don't need this endpoint and should use wakatime-cli to send heartbeats.

### Method
POST

### Endpoint
/api/v1/users/:user/heartbeats

### Scope Required
write_heartbeats
```

--------------------------------

### GET /api/v1/editors

Source: https://wakatime.com/developers

Lists WakaTime IDE plugins, their latest versions, and colors used on charts. Optionally includes unreleased plugins.

```APIDOC
## GET /api/v1/editors

### Description
List of WakaTime IDE plugins, latest plugin versions, and their color used on WakaTime charts.

### Method
GET

### Endpoint
/api/v1/editors

### Parameters
#### Query Parameters
- **unreleased** (Boolean) - Optional - Include unreleased plugins.

### Response
#### Success Response (200)
- **data** (object) - Contains editor plugin details.
  - **id** (string) - Unique id of this editor plugin.
  - **name** (string) - Display name of the editor.
  - **color** (string) - Hex color code used when displaying the editor on charts.
  - **website** (string) - Official website of the editor.
  - **repository** (string) - GitHub repository for the editor's plugin.
  - **version** (string) - Most recent plugin version available for this editor.
  - **version_url** (string) - Remote file containing this editor's most recent version.
  - **history_url** (string) - Changelog file.
  - **released** (boolean) - Whether this IDE has a WakaTime plugin available.
  - **hidden** (boolean) - Whether this IDE has been deprecated or archived, ex: Atom.

#### Response Example
{
  "data": {
    "id": "<string>",
    "name": "<string>",
    "color": "<string>",
    "website": "<string>",
    "repository": "<string>",
    "version": "<string>",
    "version_url": "<string>",
    "history_url": "<string>",
    "released": true,
    "hidden": false
  }
}
```

--------------------------------

### GET /api/v1/users/current/goals

Source: https://wakatime.com/developers

Retrieves goals for the current user.

```APIDOC
## GET /api/v1/users/current/goals

### Description
Returns a list of goals for the current user.

### Method
GET

### Endpoint
/api/v1/users/current/goals

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination.

### Response
#### Success Response (200)
- **data** (array) - List of goal objects.

#### Response Example
{
  "data": [
    {
      "id": "goal1",
      "title": "Daily Goal",
      "target_seconds": 3600
    }
  ]
}
```

--------------------------------

### POST /api/v1/users/:user/data_dumps

Source: https://wakatime.com/developers

Starts generating a data export in the background. Requires the read_heartbeats scope.

```APIDOC
## POST /api/v1/users/:user/data_dumps

### Description
Start generating a data export in the background. When finished, the percent complete will be 100 and the status 'Completed', with a 'download_url' available for downloading. An email will also be sent to the user with the download url when exporting completed.

### Method
POST

### Endpoint
/api/v1/users/:user/data_dumps

### Scope Required
read_heartbeats

### Parameters
#### Request Body
- **type** (string) - Required - Export type; Either 'daily' or 'heartbeats'.
- **email_when_finished** (boolean) - Optional - Flag to disable the email notification when exporting completed; defaults to true.

### Request Example
{
  "type": "daily",
  "email_when_finished": true
}

### Response
#### Success Response (201)
- **data** (object) - Data export object.
  - **id** (string) - Unique id of this data export.
  - **status** (string) - One of 'Pending…', 'Processing coding activity…', 'Uploading…', or 'Completed'.
  - **percent_complete** (float) - Percent of code stats that have been exported.
  - **download_url** (string) - When completed, the url to download this data export.
  - **type** (string) - Either 'heartbeats' or 'daily'.
  - **is_processing** (boolean) - Whether this data export is currently processing in the background.
  - **is_stuck** (boolean) - Whether this data export is taking too long, probably due to an error.
  - **has_failed** (boolean) - Whether this data export failed to complete due to an error.
  - **expires** (string) - Datetime when this data export can no longer be downloaded.
  - **created_at** (string) - Datetime when this data export was requested.

#### Response Example
{
  "data": {
    "id": "export123",
    "status": "Pending…",
    "percent_complete": 0.0,
    "download_url": null,
    "type": "daily",
    "is_processing": true,
    "is_stuck": false,
    "has_failed": false,
    "expires": "2023-01-01T00:00:00Z",
    "created_at": "2023-01-01T00:00:00Z"
  }
}
```

--------------------------------

### GET /api/v1/users/current

Source: https://wakatime.com/developers

Retrieves the current user's information.

```APIDOC
## GET /api/v1/users/current

### Description
Returns the current user's information.

### Method
GET

### Endpoint
/api/v1/users/current

### Response
#### Success Response (200)
- **data** (object) - User object.

#### Response Example
{
  "data": {
    "id": "user1",
    "username": "user1",
    "email": "user1@example.com"
  }
}
```

--------------------------------

### GET /api/v1/meta

Source: https://wakatime.com/developers

Retrieves information about WakaTime, including a list of public IP addresses used by WakaTime servers. Useful for firewall configuration.

```APIDOC
## GET /api/v1/meta

### Description
Information about WakaTime, such as a list of public ip addresses used by WakaTime servers.

### Method
GET

### Endpoint
/api/v1/meta

### Response
#### Success Response (200)
- **data** (object) - Contains the metadata.
  - **ip_descriptions** (object) - Explanation of each ip category (api, website, worker).
  - **ips** (object) - Lists of IP addresses.
    - **api** (list of strings) - IP addresses used by WakaTime api servers.
    - **website** (list of strings) - IP addresses used by WakaTime website servers.
    - **worker** (list of strings) - IP addresses used by WakaTime background worker servers.
  - **last_modified_at** (string) - Last time an IP was either added, removed, or modified in ISO 8601 format; use similar to etag, to sync your firewall configs only when IPs have changed.

#### Response Example
{
  "data": {
    "ip_descriptions": {},
    "ips": {
      "api": ["string"],
      "website": ["string"],
      "worker": ["string"]
    },
    "last_modified_at": "string"
  }
}
```
Tokens:
Raw