This version of GitHub Enterprise Server was discontinued on 2024-09-25. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.

Using the audit log API for your enterprise

Learn how to programmatically retrieve enterprise events with the REST API.

Who can use this feature?

Enterprise owners and site administrators

In this article

Note

Webhooks might be a good alternative to the audit log or API polling for certain use cases. Webhooks are a way for GitHub to notify your server when specific events occur for a repository, organization, or enterprise. Compared to the API or searching the audit log, webhooks can be more efficient if you just want to learn and possibly log when certain events occur on your enterprise, organization, or repository. See "Webhooks documentation."

Maintain compliance and secure intellectual property with endpoints relating to the audit log. See "REST API endpoints for enterprise audit logs" and "REST API endpoints for organizations."

For more information about the specific events that you can access via the audit log endpoints, see the following articles.

Audit log details

The audit log lists events triggered by activities that affect your enterprise. Audit logs for GitHub Enterprise Server are retained indefinitely, unless an enterprise owner configured a different retention period. 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. See "Understanding the search syntax."

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

You can use the read:audit_log scope to access the audit log via the API.

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

You can use page-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 return 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."

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"http(s)://HOSTNAME/api/v3/enterprises/avocado-corp/audit-log?phrase=created:2022-01-01&page=1&per_page=100"

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 \
"http(s)://HOSTNAME/api/v3/enterprises/avocado-corp/audit-log?phrase=action:pull_request+created:>=2022-01-01+actor:octocat"

Example 3: Events for Git activity in an enterprise, for a specific date and actor

You can search for Git events in an enterprise, such as cloning, fetching, and pushing, by adding include=git as a parameter in the URL. Alternatively, you can use include=all to search for both web events and Git events.

The query below searches for audit log events for Git activity, where the event occurred after Jan 1st, 2024, in the avocado-corp enterprise, and the action was performed by the octocat user.

curl -H "Authorization: Bearer TOKEN" \
--request GET \
"http(s)://HOSTNAME/api/v3/enterprises/avocado-corp/audit-log?phrase=created:>=2024-01-01+actor:octocat&include=git"