Use this API to track internal events and to retrieve the Service Ping payload that GitLab collects, including its non-SQL metrics and the queries behind it.
Track usage data event
POST /api/v4/usage_data/increment_counter
This feature was introduced in GitLab 13.4.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
eventRequired | String | Event name that should be tracked Example: i_ |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Track usage data event for the current user
POST /api/v4/usage_data/increment_unique_users
Request body (application/json)
| Property | Type | Description |
|---|---|---|
eventRequired | String | Event name that should be tracked Example: i_ |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
List all non-SQL metrics
GET /api/v4/usage_data/non_sql_metrics
Lists all non-SQL metrics data used in the Service ping. Administrators only.
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not Found | — |
List all Service Ping SQL queries
GET /api/v4/usage_data/queries
Lists all raw SQL queries used to compute Service Ping. Administrators only.
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
401 | Unauthorized | — |
403 | Forbidden | — |
404 | Not Found | — |
Retrieve Service Ping payload
GET /api/v4/usage_data/service_ping
Retrieves the Service Ping payload from the application cache as JSON. If no cached payload is available, returns an empty response. Requires a personal access token with the read_service_ping scope. Introduced in GitLab 16.9.
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
401 | 401 Unauthorized | — |
403 | Forbidden | — |
404 | Not found | — |
Track an internal GitLab event
POST /api/v4/usage_data/track_event
Tracks a GitLab internal event. This action increments Service Ping counters in Redis and is optionally sent to Snowplow. Introduced in GitLab 16.2.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
additional_ | Object | Additional properties to be tracked Example: {"label": |
eventRequired | String | Name of the event to track Example: i_ |
namespace_ | Integer | ID of the namespace associated with the event Example: 1234 |
project_ | Integer | ID of the project.project_Example: 1234 |
project_ | String | Path of the project.project_ when it is not provided.project_Example: namespace/ |
send_ | Boolean | If true,Example: true |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
400 | Bad Request | — |
401 | Unauthorized | — |
404 | Not found | — |
Track multiple internal GitLab events
POST /api/v4/usage_data/track_events
Tracks one or more GitLab internal events in a single request. Each event increments Service Ping counters in Redis and is optionally sent to Snowplow. This feature was introduced in GitLab 17.3.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
eventsRequired | Array of objects | Array of internal events to track. |
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | — |
400 | Validation error | — |
401 | Unauthorized | — |