Skip to main content

GitHub AE is currently under limited release.

Using the audit log API for your enterprise

You can programmatically retrieve enterprise events with the REST API.

Who can use this feature

Enterprise owners can use the audit log API.

Using the audit log API

You can maintain compliance for your enterprise and secure your intellectual property by interacting with the audit log using the REST API. For more information about the specific events that you can access via the audit log API, see the following articles.

The audit log lists events triggered by activities that affect your enterprise. Audit logs for GitHub AE are retained indefinitely, unless an enterprise owner configured a different retention period. For more information, see "Configuring the audit log for your enterprise."

By default, only events from the past three months are displayed. To view older events, you must specify a date range with the created parameter. For more information, see "Understanding the search syntax."

Timestamps and date fields in the API response are measured in UTC epoch milliseconds.

For more information about the audit log REST API, see "GitHub Enterprise administration" and "Organizations."

Example 1: All events in an enterprise, for a specific date, with pagination

You can use cursor based pagination. For more information about pagination, see "Using pagination in the REST API."

The query below searches for audit log events created on Jan 1st, 2022 in the avocado-corp enterprise, and returns the first page with a maximum of 100 items per page using pagination. For more information about pagination, see "Using pagination in the REST API." The --include flag causes the headers to be returned along with the response.

curl --include -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&per_page=100"

If there are more than 100 results, the link header will include URLs to fetch the next, first, and previous pages of results.

link: <https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42NjQzODMzNTk5MjdlKzEyfDloQzBxdURzaFdVbVlLWjkxRU9mNXc%3D&before=>; rel="next",
<https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=>; rel="first",
<https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=&before=MS42Njc4NDA2MjM4MzNlKzEyfExqeG5sUElvNEZMbG1XZHA5akdKTVE%3D>; rel="prev"

Copy the corresponding pagination link into your next request. For example:

curl -I -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/13827/audit-log?%3A2022-11-01=&per_page=100&after=MS42Njc4NDA2MjM5NDFlKzEyfHRYa3AwSkxUd2xyRjA5bWxfOS1RbFE%3D&before="

Example 2: Events for pull requests in an enterprise, for a specific date and actor

You can specify multiple search phrases, such as created and actor, by separating them in your formed URL with the + symbol or ASCII character code %20.

The query below searches for audit log events for pull requests, where the event occurred on or after Jan 1st, 2022 in the avocado-corp enterprise, and the action was performed by the octocat user:

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"https://api.github.com/enterprises/avocado-corp/audit-log?phrase=action:pull_request+created:>=2022-01-01+actor:octocat"