Audit Events API premium
Version history
- Introduced in GitLab 12.4.
- Author Email added to the response body in GitLab 15.9.
Instance Audit Events premiumself-managed
The Audit Events API allows you to retrieve instance audit events. This API cannot retrieve group or project audit events.
To retrieve audit events using the API, you must authenticate yourself as an Administrator.
Retrieve all instance audit events
Support for keyset pagination introduced in GitLab 15.11.
GET /audit_events
| Attribute | Type | Required | Description |
|---|---|---|---|
created_after | string | no | Return audit events created on or after the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) |
created_before | string | no | Return audit events created on or before the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) |
entity_type | string | no | Return audit events for the given entity type. Valid values are: User, Group, or Project. |
entity_id | integer | no | Return audit events for the given entity ID. Requires entity_type attribute to be present. |
This endpoint supports both offset-based and keyset-based pagination. You should use keyset-based pagination when requesting consecutive pages of results.
Read more on pagination.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/audit_events"
Example response:
[
{
"id": 1,
"author_id": 1,
"entity_id": 6,
"entity_type": "Project",
"details": {
"custom_message": "Project archived",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": "flightjs/flight",
"target_type": "Project",
"target_details": "flightjs/flight",
"ip_address": "127.0.0.1",
"entity_path": "flightjs/flight"
},
"created_at": "2019-08-30T07:00:41.885Z"
},
{
"id": 2,
"author_id": 1,
"entity_id": 60,
"entity_type": "Group",
"details": {
"add": "group",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": "flightjs",
"target_type": "Group",
"target_details": "flightjs",
"ip_address": "127.0.0.1",
"entity_path": "flightjs"
},
"created_at": "2019-08-27T18:36:44.162Z"
},
{
"id": 3,
"author_id": 51,
"entity_id": 51,
"entity_type": "User",
"details": {
"change": "email address",
"from": "hello@flightjs.com",
"to": "maintainer@flightjs.com",
"author_name": "Andreas",
"author_email": "admin@example.com",
"target_id": 51,
"target_type": "User",
"target_details": "Andreas",
"ip_address": null,
"entity_path": "Andreas"
},
"created_at": "2019-08-22T16:34:25.639Z"
}
]
Retrieve single instance audit event
GET /audit_events/:id
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer | yes | The ID of the audit event |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/audit_events/1"
Example response:
{
"id": 1,
"author_id": 1,
"entity_id": 6,
"entity_type": "Project",
"details": {
"custom_message": "Project archived",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": "flightjs/flight",
"target_type": "Project",
"target_details": "flightjs/flight",
"ip_address": "127.0.0.1",
"entity_path": "flightjs/flight"
},
"created_at": "2019-08-30T07:00:41.885Z"
}
Group Audit Events
Version history
- Introduced in GitLab 12.5.
- Support for keyset pagination added in GitLab 15.2.
- Also returning project audit events for projects within the given group was introduced in GitLab 16.1 behind feature flag
audit_event_group_rollup. Disabled by default.
On self-managed GitLab, by default returning project audit events for projects within the given group is not available. To make it available, ask an administrator
to enable the feature flag named
audit_event_group_rollup. On GitLab.com, this feature is not available. The feature is not ready for
production use.The Group Audit Events API allows you to retrieve group audit events.
A user with:
- The Owner role can retrieve group audit events of all users.
- The Developer or Maintainer role is limited to group audit events based on their individual actions.
This endpoint supports both offset-based and keyset-based pagination. Keyset-based pagination is recommended when requesting consecutive pages of results.
Retrieve all group audit events
Support for keyset pagination introduced in GitLab 15.2.
GET /groups/:id/audit_events
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the group |
created_after | string | no | Return group audit events created on or after the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
|
created_before | string | no | Return group audit events created on or before the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) |
By default, GET requests return 20 results at a time because the API results
are paginated.
Read more on pagination.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/groups/60/audit_events"
Example response:
[
{
"id": 2,
"author_id": 1,
"entity_id": 60,
"entity_type": "Group",
"details": {
"custom_message": "Group marked for deletion",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": "flightjs",
"target_type": "Group",
"target_details": "flightjs",
"ip_address": "127.0.0.1",
"entity_path": "flightjs"
},
"created_at": "2019-08-28T19:36:44.162Z"
},
{
"id": 1,
"author_id": 1,
"entity_id": 60,
"entity_type": "Group",
"details": {
"add": "group",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": "flightjs",
"target_type": "Group",
"target_details": "flightjs",
"ip_address": "127.0.0.1",
"entity_path": "flightjs"
},
"created_at": "2019-08-27T18:36:44.162Z"
}
]
Retrieve a specific group audit event
Only available to group owners and administrators.
GET /groups/:id/audit_events/:audit_event_id
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the group |
audit_event_id | integer | yes | The ID of the audit event |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/groups/60/audit_events/2"
Example response:
{
"id": 2,
"author_id": 1,
"entity_id": 60,
"entity_type": "Group",
"details": {
"custom_message": "Group marked for deletion",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": "flightjs",
"target_type": "Group",
"target_details": "flightjs",
"ip_address": "127.0.0.1",
"entity_path": "flightjs"
},
"created_at": "2019-08-28T19:36:44.162Z"
}
Project Audit Events
Introduced in GitLab 13.1.
The Project Audit Events API allows you to retrieve project audit events.
A user with a Maintainer role (or above) can retrieve project audit events of all users. A user with a Developer role is limited to project audit events based on their individual actions.
Retrieve all project audit events
Support for keyset pagination introduced in GitLab 15.10.
GET /projects/:id/audit_events
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the project |
created_after | string | no | Return project audit events created on or after the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) |
created_before | string | no | Return project audit events created on or before the given time. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ) |
By default, GET requests return 20 results at a time because the API results are paginated.
When requesting consecutive pages of results, you should use keyset pagination.
Read more on pagination.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/projects/7/audit_events"
Example response:
[
{
"id": 5,
"author_id": 1,
"entity_id": 7,
"entity_type": "Project",
"details": {
"change": "prevent merge request approval from committers",
"from": "",
"to": "true",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": 7,
"target_type": "Project",
"target_details": "twitter/typeahead-js",
"ip_address": "127.0.0.1",
"entity_path": "twitter/typeahead-js"
},
"created_at": "2020-05-26T22:55:04.230Z"
},
{
"id": 4,
"author_id": 1,
"entity_id": 7,
"entity_type": "Project",
"details": {
"change": "prevent merge request approval from authors",
"from": "false",
"to": "true",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": 7,
"target_type": "Project",
"target_details": "twitter/typeahead-js",
"ip_address": "127.0.0.1",
"entity_path": "twitter/typeahead-js"
},
"created_at": "2020-05-26T22:55:04.218Z"
}
]
Retrieve a specific project audit event
Only available to users with at least the Maintainer role for the project.
GET /projects/:id/audit_events/:audit_event_id
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer/string | yes | The ID or URL-encoded path of the project |
audit_event_id | integer | yes | The ID of the audit event |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/projects/7/audit_events/5"
Example response:
{
"id": 5,
"author_id": 1,
"entity_id": 7,
"entity_type": "Project",
"details": {
"change": "prevent merge request approval from committers",
"from": "",
"to": "true",
"author_name": "Administrator",
"author_email": "admin@example.com",
"target_id": 7,
"target_type": "Project",
"target_details": "twitter/typeahead-js",
"ip_address": "127.0.0.1",
"entity_path": "twitter/typeahead-js"
},
"created_at": "2020-05-26T22:55:04.230Z"
}