2020-10-26 17:08:22 -04:00
---
2021-04-23 11:09:37 -04:00
stage: Manage
group: Compliance
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-26 17:08:22 -04:00
---
2021-09-08 05:09:10 -04:00
# Events API **(FREE)**
2017-05-29 01:49:17 -04:00
## Filter parameters
### Action Types
2021-06-22 11:06:55 -04:00
Available types for the `action` parameter, and the resources that might be affected:
2017-05-29 01:49:17 -04:00
2020-11-12 16:09:19 -05:00
- `approved`
2021-06-22 11:06:55 -04:00
- Merge request
2017-05-29 01:49:17 -04:00
- `closed`
2021-09-08 05:09:10 -04:00
- Epic ** (PREMIUM)**
2021-06-22 11:06:55 -04:00
- Issue
- Merge request
- Milestone
- `commented` on any `Noteable` record.
- Alert
- Commit
- Design
- Issue
- Merge request
- Snippet
- `created`
- Design
2021-09-08 05:09:10 -04:00
- Epic ** (PREMIUM)**
2021-06-22 11:06:55 -04:00
- Issue
- Merge request
- Milestone
- Project
- Wiki page
2017-05-29 01:49:17 -04:00
- `destroyed`
2021-06-22 11:06:55 -04:00
- Design
- Milestone
- Wiki page
2017-05-29 01:49:17 -04:00
- `expired`
2021-06-22 11:06:55 -04:00
- Project membership
- `joined`
- Project membership
- `left`
- Project membership
- `merged`
- Merge request
- `pushed` commits to (or deleted commits from) a repository, individually or in bulk.
- Project
- `reopened`
2021-09-08 05:09:10 -04:00
- Epic ** (PREMIUM)**
2021-06-22 11:06:55 -04:00
- Issue
- Merge request
- Milestone
- `updated`
- Design
- Wiki page
2017-05-29 01:49:17 -04:00
2021-07-28 17:08:53 -04:00
These options are in lowercase.
2017-05-29 01:49:17 -04:00
### Target Types
Available target types for the `target_type` parameter are:
- `issue`
- `milestone`
- `merge_request`
- `note`
- `project`
- `snippet`
- `user`
2021-07-28 17:08:53 -04:00
These options are in lowercase.
2017-05-29 01:49:17 -04:00
### Date formatting
Dates for the `before` and `after` parameters should be supplied in the following format:
2020-02-27 04:09:01 -05:00
```plaintext
2017-05-29 01:49:17 -04:00
YYYY-MM-DD
```
2018-03-22 14:55:26 -04:00
### Event Time Period Limit
2021-08-11 02:10:02 -04:00
GitLab removes events older than 3 years from the events table for performance reasons.
2018-03-22 14:55:26 -04:00
2017-05-29 01:49:17 -04:00
## List currently authenticated user's events
2018-07-15 09:00:48 -04:00
Get a list of events for the authenticated user. Scope `read_user` or `api` is required.
2017-05-29 01:49:17 -04:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-05-29 01:49:17 -04:00
GET /events
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-04-21 11:21:10 -04:00
| `action` | string | no | Include only events of a particular [action type ](#action-types ) |
| `target_type` | string | no | Include only events of a particular [target type ](#target-types ) |
2021-05-04 11:10:36 -04:00
| `before` | date | no | Include only events created before a particular date. [View how to format dates ](#date-formatting ). |
| `after` | date | no | Include only events created after a particular date. [View how to format dates ](#date-formatting ). |
2019-12-18 13:08:04 -05:00
| `scope` | string | no | Include all events across a user's projects. |
2021-05-04 11:10:36 -04:00
| `sort` | string | no | Sort events in `asc` or `desc` order by `created_at` . Default is `desc` . |
2017-05-29 01:49:17 -04:00
Example request:
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/events?target_type=issue& action=created& after=2017-01-31& before=2017-03-01& scope=all"
2017-05-29 01:49:17 -04:00
```
Example response:
```json
[
{
2020-08-19 05:09:58 -04:00
"id": 1,
2017-05-29 01:49:17 -04:00
"title":null,
"project_id":1,
"action_name":"opened",
"target_id":160,
"target_type":"Issue",
"author_id":25,
"target_title":"Qui natus eos odio tempore et quaerat consequuntur ducimus cupiditate quis.",
"created_at":"2017-02-09T10:43:19.667Z",
"author":{
"name":"User 3",
"username":"user3",
"id":25,
"state":"active",
"avatar_url":"http://www.gravatar.com/avatar/97d6d9441ff85fdc730e02a6068d267b?s=80\u0026d=identicon",
"web_url":"https://gitlab.example.com/user3"
},
"author_username":"user3"
},
{
2020-08-19 05:09:58 -04:00
"id": 2,
2017-05-29 01:49:17 -04:00
"title":null,
"project_id":1,
"action_name":"opened",
"target_id":159,
"target_type":"Issue",
"author_id":21,
"target_title":"Nostrum enim non et sed optio illo deleniti non.",
"created_at":"2017-02-09T10:43:19.426Z",
"author":{
"name":"Test User",
"username":"ted",
"id":21,
"state":"active",
"avatar_url":"http://www.gravatar.com/avatar/80fb888c9a48b9a3f87477214acaa63f?s=80\u0026d=identicon",
"web_url":"https://gitlab.example.com/ted"
},
"author_username":"ted"
}
]
```
### Get user contribution events
2018-07-15 09:00:48 -04:00
Get the contribution events for the specified user, sorted from newest to oldest. Scope `read_user` or `api` is required.
2017-05-29 01:49:17 -04:00
2020-02-27 04:09:01 -05:00
```plaintext
2017-05-29 01:49:17 -04:00
GET /users/:id/events
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2017-06-01 23:41:47 -04:00
| `id` | integer | yes | The ID or Username of the user |
2020-04-21 11:21:10 -04:00
| `action` | string | no | Include only events of a particular [action type ](#action-types ) |
| `target_type` | string | no | Include only events of a particular [target type ](#target-types ) |
2021-05-04 11:10:36 -04:00
| `before` | date | no | Include only events created before a particular date. [View how to format dates ](#date-formatting ). |
| `after` | date | no | Include only events created after a particular date. [View how to format dates ](#date-formatting ). |
| `sort` | string | no | Sort events in `asc` or `desc` order by `created_at` . Default is `desc` . |
2021-04-06 11:09:23 -04:00
| `page` | integer | no | The page of results to return. Defaults to 1. |
| `per_page` | integer | no | The number of results per page. Defaults to 20. |
2017-05-29 01:49:17 -04:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/users/:id/events"
2017-05-29 01:49:17 -04:00
```
Example response:
```json
[
{
2020-08-19 05:09:58 -04:00
"id": 3,
2017-05-29 01:49:17 -04:00
"title": null,
"project_id": 15,
"action_name": "closed",
"target_id": 830,
"target_type": "Issue",
"author_id": 1,
"target_title": "Public project search field",
"author": {
"name": "Dmitriy Zaporozhets",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
"web_url": "http://localhost:3000/root"
},
"author_username": "root"
},
{
2020-08-19 05:09:58 -04:00
"id": 4,
2017-05-29 01:49:17 -04:00
"title": null,
"project_id": 15,
Migrate events into a new format
This commit migrates events data in such a way that push events are
stored much more efficiently. This is done by creating a shadow table
called "events_for_migration", and a table called "push_event_payloads"
which is used for storing push data of push events. The background
migration in this commit will copy events from the "events" table into
the "events_for_migration" table, push events in will also have a row
created in "push_event_payloads".
This approach allows us to reclaim space in the next release by simply
swapping the "events" and "events_for_migration" tables, then dropping
the old events (now "events_for_migration") table.
The new table structure is also optimised for storage space, and does
not include the unused "title" column nor the "data" column (since this
data is moved to "push_event_payloads").
== Newly Created Events
Newly created events are inserted into both "events" and
"events_for_migration", both using the exact same primary key value. The
table "push_event_payloads" in turn has a foreign key to the _shadow_
table. This removes the need for recreating and validating the foreign
key after swapping the tables. Since the shadow table also has a foreign
key to "projects.id" we also don't have to worry about orphaned rows.
This approach however does require some additional storage as we're
duplicating a portion of the events data for at least 1 release. The
exact amount is hard to estimate, but for GitLab.com this is expected to
be between 10 and 20 GB at most. The background migration in this commit
deliberately does _not_ update the "events" table as doing so would put
a lot of pressure on PostgreSQL's auto vacuuming system.
== Supporting Both Old And New Events
Application code has also been adjusted to support push events using
both the old and new data formats. This is done by creating a PushEvent
class which extends the regular Event class. Using Rails' Single Table
Inheritance system we can ensure the right class is used for the right
data, which in this case is based on the value of `events.action`. To
support displaying old and new data at the same time the PushEvent class
re-defines a few methods of the Event class, falling back to their
original implementations for push events in the old format.
Once all existing events have been migrated the various push event
related methods can be removed from the Event model, and the calls to
`super` can be removed from the methods in the PushEvent model.
The UI and event atom feed have also been slightly changed to better
handle this new setup, fortunately only a few changes were necessary to
make this work.
== API Changes
The API only displays push data of events in the new format. Supporting
both formats in the API is a bit more difficult compared to the UI.
Since the old push data was not really well documented (apart from one
example that used an incorrect "action" nmae) I decided that supporting
both was not worth the effort, especially since events will be migrated
in a few days _and_ new events are created in the correct format.
2017-07-10 11:43:57 -04:00
"action_name": "pushed",
2017-05-29 01:49:17 -04:00
"target_id": null,
"target_type": null,
"author_id": 1,
"author": {
"name": "Dmitriy Zaporozhets",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
"web_url": "http://localhost:3000/root"
},
"author_username": "john",
Migrate events into a new format
This commit migrates events data in such a way that push events are
stored much more efficiently. This is done by creating a shadow table
called "events_for_migration", and a table called "push_event_payloads"
which is used for storing push data of push events. The background
migration in this commit will copy events from the "events" table into
the "events_for_migration" table, push events in will also have a row
created in "push_event_payloads".
This approach allows us to reclaim space in the next release by simply
swapping the "events" and "events_for_migration" tables, then dropping
the old events (now "events_for_migration") table.
The new table structure is also optimised for storage space, and does
not include the unused "title" column nor the "data" column (since this
data is moved to "push_event_payloads").
== Newly Created Events
Newly created events are inserted into both "events" and
"events_for_migration", both using the exact same primary key value. The
table "push_event_payloads" in turn has a foreign key to the _shadow_
table. This removes the need for recreating and validating the foreign
key after swapping the tables. Since the shadow table also has a foreign
key to "projects.id" we also don't have to worry about orphaned rows.
This approach however does require some additional storage as we're
duplicating a portion of the events data for at least 1 release. The
exact amount is hard to estimate, but for GitLab.com this is expected to
be between 10 and 20 GB at most. The background migration in this commit
deliberately does _not_ update the "events" table as doing so would put
a lot of pressure on PostgreSQL's auto vacuuming system.
== Supporting Both Old And New Events
Application code has also been adjusted to support push events using
both the old and new data formats. This is done by creating a PushEvent
class which extends the regular Event class. Using Rails' Single Table
Inheritance system we can ensure the right class is used for the right
data, which in this case is based on the value of `events.action`. To
support displaying old and new data at the same time the PushEvent class
re-defines a few methods of the Event class, falling back to their
original implementations for push events in the old format.
Once all existing events have been migrated the various push event
related methods can be removed from the Event model, and the calls to
`super` can be removed from the methods in the PushEvent model.
The UI and event atom feed have also been slightly changed to better
handle this new setup, fortunately only a few changes were necessary to
make this work.
== API Changes
The API only displays push data of events in the new format. Supporting
both formats in the API is a bit more difficult compared to the UI.
Since the old push data was not really well documented (apart from one
example that used an incorrect "action" nmae) I decided that supporting
both was not worth the effort, especially since events will be migrated
in a few days _and_ new events are created in the correct format.
2017-07-10 11:43:57 -04:00
"push_data": {
"commit_count": 1,
"action": "pushed",
"ref_type": "branch",
"commit_from": "50d4420237a9de7be1304607147aec22e4a14af7",
"commit_to": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
"ref": "master",
"commit_title": "Add simple search to projects in public area"
2017-05-29 01:49:17 -04:00
},
"target_title": null
},
{
2020-08-19 05:09:58 -04:00
"id": 5,
2017-05-29 01:49:17 -04:00
"title": null,
"project_id": 15,
"action_name": "closed",
"target_id": 840,
"target_type": "Issue",
"author_id": 1,
"target_title": "Finish & merge Code search PR",
"author": {
"name": "Dmitriy Zaporozhets",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
"web_url": "http://localhost:3000/root"
},
"author_username": "root"
},
{
2020-08-19 05:09:58 -04:00
"id": 7,
2017-05-29 01:49:17 -04:00
"title": null,
"project_id": 15,
"action_name": "commented on",
"target_id": 1312,
"target_type": "Note",
"author_id": 1,
"target_title": null,
"created_at": "2015-12-04T10:33:58.089Z",
"note": {
"id": 1312,
"body": "What an awesome day!",
"attachment": null,
"author": {
"name": "Dmitriy Zaporozhets",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
"web_url": "http://localhost:3000/root"
},
"created_at": "2015-12-04T10:33:56.698Z",
"system": false,
"noteable_id": 377,
"noteable_type": "Issue"
},
"author": {
"name": "Dmitriy Zaporozhets",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://localhost:3000/uploads/user/avatar/1/fox_avatar.png",
"web_url": "http://localhost:3000/root"
},
"author_username": "root"
}
]
```
## List a Project's visible events
2020-12-04 16:09:29 -05:00
NOTE:
2020-07-23 14:10:06 -04:00
This endpoint has been around longer than the others. Documentation was formerly located in the [Projects API pages ](projects.md ).
2017-05-29 01:49:17 -04:00
Get a list of visible events for a particular project.
2020-02-27 04:09:01 -05:00
```plaintext
2018-08-10 04:56:52 -04:00
GET /projects/:project_id/events
2017-05-29 01:49:17 -04:00
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-06-28 11:08:03 -04:00
| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2020-04-21 11:21:10 -04:00
| `action` | string | no | Include only events of a particular [action type ](#action-types ) |
| `target_type` | string | no | Include only events of a particular [target type ](#target-types ) |
2021-05-04 11:10:36 -04:00
| `before` | date | no | Include only events created before a particular date. [View how to format dates ](#date-formatting ). |
| `after` | date | no | Include only events created after a particular date. [View how to format dates ](#date-formatting ). |
| `sort` | string | no | Sort events in `asc` or `desc` order by `created_at` . Default is `desc` . |
2017-05-29 01:49:17 -04:00
Example request:
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/:project_id/events?target_type=issue& action=created& after=2017-01-31& before=2017-03-01"
2017-05-29 01:49:17 -04:00
```
Example response:
```json
[
{
2021-04-29 08:09:58 -04:00
"id": 8,
2017-05-29 01:49:17 -04:00
"title":null,
"project_id":1,
"action_name":"opened",
"target_id":160,
2017-08-02 02:18:17 -04:00
"target_iid":160,
2017-05-29 01:49:17 -04:00
"target_type":"Issue",
"author_id":25,
"target_title":"Qui natus eos odio tempore et quaerat consequuntur ducimus cupiditate quis.",
"created_at":"2017-02-09T10:43:19.667Z",
"author":{
"name":"User 3",
"username":"user3",
"id":25,
"state":"active",
"avatar_url":"http://www.gravatar.com/avatar/97d6d9441ff85fdc730e02a6068d267b?s=80\u0026d=identicon",
"web_url":"https://gitlab.example.com/user3"
},
"author_username":"user3"
},
{
2020-08-19 05:09:58 -04:00
"id": 9,
2017-05-29 01:49:17 -04:00
"title":null,
"project_id":1,
"action_name":"opened",
"target_id":159,
2017-08-02 02:18:17 -04:00
"target_iid":159,
2017-05-29 01:49:17 -04:00
"target_type":"Issue",
"author_id":21,
"target_title":"Nostrum enim non et sed optio illo deleniti non.",
"created_at":"2017-02-09T10:43:19.426Z",
"author":{
"name":"Test User",
"username":"ted",
"id":21,
"state":"active",
"avatar_url":"http://www.gravatar.com/avatar/80fb888c9a48b9a3f87477214acaa63f?s=80\u0026d=identicon",
"web_url":"https://gitlab.example.com/ted"
},
"author_username":"ted"
2017-08-08 07:31:55 -04:00
},
{
2020-08-19 05:09:58 -04:00
"id": 10,
2017-08-08 07:31:55 -04:00
"title": null,
"project_id": 1,
"action_name": "commented on",
"target_id": 1312,
"target_iid": 1312,
"target_type": "Note",
"author_id": 1,
"data": null,
"target_title": null,
"created_at": "2015-12-04T10:33:58.089Z",
"note": {
"id": 1312,
"body": "What an awesome day!",
"attachment": null,
"author": {
"name": "Dmitriy Zaporozhets",
"username": "root",
"id": 1,
"state": "active",
2019-08-26 23:01:05 -04:00
"avatar_url": "https://gitlab.example.com/uploads/user/avatar/1/fox_avatar.png",
"web_url": "https://gitlab.example.com/root"
2017-08-08 07:31:55 -04:00
},
"created_at": "2015-12-04T10:33:56.698Z",
"system": false,
"noteable_id": 377,
"noteable_type": "Issue",
"noteable_iid": 377
},
"author": {
"name": "Dmitriy Zaporozhets",
"username": "root",
"id": 1,
"state": "active",
2019-08-26 23:01:05 -04:00
"avatar_url": "https://gitlab.example.com/uploads/user/avatar/1/fox_avatar.png",
"web_url": "https://gitlab.example.com/root"
2017-08-08 07:31:55 -04:00
},
"author_username": "root"
2017-05-29 01:49:17 -04:00
}
]
```
