diff --git a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise.md b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise.md index 1299f5aa4e7a..1d2e92514c76 100644 --- a/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise.md +++ b/content/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/using-the-audit-log-api-for-your-enterprise.md @@ -1,8 +1,8 @@ --- title: Using the audit log API for your enterprise -intro: You can programmatically retrieve enterprise events with the REST API. +intro: Learn how to programmatically retrieve enterprise events with the REST API. shortTitle: Audit log API -permissions: 'Enterprise owners {% ifversion ghes %}and site administrators {% endif %}can use the audit log API.' +permissions: 'Enterprise owners {% ifversion ghes %}and site administrators {% endif %}' versions: ghec: '*' ghes: '*' @@ -14,29 +14,29 @@ topics: - API --- -## Using the audit log API +>[!NOTE] {% data reusables.webhooks.webhooks-as-audit-log-alternative %} -{% note %} +Maintain compliance and secure intellectual property with endpoints relating to the audit log. See "[AUTOTITLE](/rest/enterprise-admin/audit-log)" and "[AUTOTITLE](/rest/orgs#get-the-audit-log-for-an-organization)." -**Note:** {% data reusables.webhooks.webhooks-as-audit-log-alternative %} - -{% endnote %} - -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. +For more information about the specific events that you can access via the audit log endpoints, see the following articles. * "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise)" * "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization)" * "[AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events)" +## Audit log details + {% data reusables.audit_log.retention-periods %} Timestamps and date fields in the API response are measured in [UTC epoch milliseconds](https://en.wikipedia.org/wiki/Unix_time). {% ifversion read-audit-scope %}You can use the `read:audit_log` scope to access the audit log via the API.{% endif %} -{% ifversion ghec %}Each audit log API endpoint has a rate limit of 1,750 queries per hour for a given combination of user and IP address. To avoid rate limiting, integrations that query the audit log API should query at a maximum frequency of 1,750 queries per hour. Additionally, if your integration receives a rate limit error (typically a 403 or 429 response), it should wait before making another request to the API. For more information, see "[AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)" and "[AUTOTITLE](/rest/guides/best-practices-for-integrators)."{% endif %} +{% ifversion ghec %} + +## Rate limit -For more information about the audit log REST API, see "[AUTOTITLE](/rest/enterprise-admin/audit-log)" and "[AUTOTITLE](/rest/orgs#get-the-audit-log-for-an-organization)." +Each audit log API endpoint has a rate limit of 1,750 queries per hour for a given combination of user and IP address. To avoid rate limiting, integrations that query the audit log API should query at a maximum frequency of 1,750 queries per hour. Additionally, if your integration receives a rate limit error (typically a 403 or 429 response), it should wait before making another request to the API. See "[AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api)" and "[AUTOTITLE](/rest/guides/best-practices-for-integrators)."{% endif %} ## Example 1: All events in an enterprise, for a specific date, with pagination diff --git a/data/reusables/audit_log/only-three-months-displayed.md b/data/reusables/audit_log/only-three-months-displayed.md index 7658ef875796..baf8a184de48 100644 --- a/data/reusables/audit_log/only-three-months-displayed.md +++ b/data/reusables/audit_log/only-three-months-displayed.md @@ -1 +1 @@ -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 "[AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates)." +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 "[AUTOTITLE](/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates)." diff --git a/data/reusables/audit_log/retention-periods.md b/data/reusables/audit_log/retention-periods.md index 1969796f9a11..c4bcb79fe921 100644 --- a/data/reusables/audit_log/retention-periods.md +++ b/data/reusables/audit_log/retention-periods.md @@ -1,3 +1,3 @@ -The audit log lists events triggered by activities that affect your enterprise{% ifversion not ghec %}. Audit logs for {% data variables.product.product_name %} are retained indefinitely{% ifversion audit-data-retention-tab %}, unless an enterprise owner configured a different retention period. For more information, see "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise)."{% else %}.{% endif %}{% else %} within the last 180 days. {% data reusables.audit_log.git-events-retention-period %}{% endif %} +The audit log lists events triggered by activities that affect your enterprise{% ifversion not ghec %}. Audit logs for {% data variables.product.product_name %} are retained indefinitely{% ifversion audit-data-retention-tab %}, unless an enterprise owner configured a different retention period. See "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/configuring-the-audit-log-for-your-enterprise)."{% else %}.{% endif %}{% else %} within the last 180 days. {% data reusables.audit_log.git-events-retention-period %}{% endif %} {% data reusables.audit_log.only-three-months-displayed %} diff --git a/data/reusables/webhooks/webhooks-as-audit-log-alternative.md b/data/reusables/webhooks/webhooks-as-audit-log-alternative.md index a80d618c2701..83e1754e71d5 100644 --- a/data/reusables/webhooks/webhooks-as-audit-log-alternative.md +++ b/data/reusables/webhooks/webhooks-as-audit-log-alternative.md @@ -1 +1 @@ -Webhooks might be a good alternative to the audit log or API polling for certain use cases. Webhooks are a way for {% data variables.product.company_short %} 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. For more information, see "[AUTOTITLE](/webhooks)." +Webhooks might be a good alternative to the audit log or API polling for certain use cases. Webhooks are a way for {% data variables.product.company_short %} 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 "[AUTOTITLE](/webhooks)."