|
| 1 | +--- |
| 2 | +title: Best practices for configuring API rate limits |
| 3 | +shortTitle: API rate limits best practices |
| 4 | +intro: 'A data-driven approach to API rate limits protects your {% data variables.product.prodname_ghe_server %} instance from excessive usage without disrupting critical integrations.' |
| 5 | +permissions: Site administrators can configure rate limits for a {% data variables.product.prodname_ghe_server %} instance. |
| 6 | +versions: |
| 7 | + ghes: '*' |
| 8 | +contentType: how-tos |
| 9 | +category: |
| 10 | + - Enable GitHub features for your enterprise |
| 11 | +--- |
| 12 | + |
| 13 | +## About a data-driven approach to rate limits |
| 14 | + |
| 15 | +Without rate limits, a single CI integration making tens of thousands of requests per hour can slow down your entire instance for every user. But setting limits too aggressively can break the integrations your teams rely on. A data-driven approach helps you find the right balance—start by observing real usage patterns, then gradually enforce limits based on the data you collect. |
| 16 | + |
| 17 | +The approach follows these phases: |
| 18 | + |
| 19 | +1. **Observe**: Enable log forwarding and analyze API traffic patterns. |
| 20 | +1. **Baseline**: Enable rate limits with a high initial value to start collecting rate limit data. |
| 21 | +1. **Refine**: Adjust limits based on observed usage and communicate with affected teams. |
| 22 | +1. **Maintain**: Continuously monitor and adjust limits over time. |
| 23 | + |
| 24 | +For information about enabling rate limits through the {% data variables.enterprise.management_console %}, see [AUTOTITLE](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits). |
| 25 | + |
| 26 | +## Prerequisites |
| 27 | + |
| 28 | +Before you begin, make sure you have: |
| 29 | + |
| 30 | +* Admin access to the {% data variables.enterprise.management_console %} |
| 31 | +* Access to log forwarding configuration |
| 32 | +* The ability to analyze centralized logs |
| 33 | +* An understanding of your organization's API usage patterns and critical integrations |
| 34 | + |
| 35 | +## Step 1: Enable log forwarding |
| 36 | + |
| 37 | +Use log forwarding to centralize API request logs for monitoring and analysis. For more information, see [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/log-forwarding). |
| 38 | + |
| 39 | +When analyzing forwarded logs, focus on these key fields: |
| 40 | + |
| 41 | +| Field | Description | |
| 42 | +|-------|-------------| |
| 43 | +| `Timestamp` | Tracks when requests are made | |
| 44 | +| `user` / `gh.actor.login` | Identifies the user or integration making requests | |
| 45 | +| `path_info` / `gh.request.api.route` | The API route being accessed | |
| 46 | +| `status` | HTTP response code (for example, `200` for success or `429` when rate limited) | |
| 47 | +| `user_agent` | Identifies the client or integration sending the request | |
| 48 | + |
| 49 | +## Step 2: Analyze API trends before enabling limits |
| 50 | + |
| 51 | +Before enabling rate limits, analyze your overall usage trends to establish a baseline: |
| 52 | + |
| 53 | +* **Identify top consumers.** Find users or integrations making the highest number of requests. |
| 54 | +* **Review high-demand endpoints.** Highlight API routes (`path_info`) that receive the most traffic and may benefit from optimization. |
| 55 | +* **Detect inefficient patterns.** Look for signs of heavy or inefficient usage, such as frequent polling without caching or redundant requests. |
| 56 | + |
| 57 | +This baseline data will help you set rate limits that are informed by actual usage rather than guesswork. |
| 58 | + |
| 59 | +## Step 3: Enable rate limits with a high initial value |
| 60 | + |
| 61 | +When you're ready to enable rate limits, start with a high threshold so you can gather additional data without disrupting existing workflows. |
| 62 | + |
| 63 | +1. In the {% data variables.enterprise.management_console %}, set the primary API rate limit to a high value, such as 25,000 requests per hour. For more information, see [AUTOTITLE](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits#enabling-rate-limits-for-the-github-enterprise-server-apis). |
| 64 | +1. After enabling rate limits, monitor the `gh.rate_limit` fields that appear in your forwarded logs: |
| 65 | + |
| 66 | + | Field | Description | |
| 67 | + |-------|-------------| |
| 68 | + | `gh.rate_limit.primary.max` | Maximum allowed requests | |
| 69 | + | `gh.rate_limit.primary.remaining` | Remaining requests in the current period | |
| 70 | + | `gh.rate_limit.primary.used` | Requests already made in the period | |
| 71 | + | `gh.rate_limit.primary.reset` | Unix timestamp when the rate limit period resets | |
| 72 | + |
| 73 | +## Step 4: Refine limits and address heavy usage |
| 74 | + |
| 75 | +Use the data from the `gh.rate_limit` fields to make informed decisions: |
| 76 | + |
| 77 | +* **Identify users nearing the limit.** Find users or integrations that are frequently approaching or exceeding the threshold. |
| 78 | +* **Determine appropriate limits.** Set rate limits based on observed usage trends rather than arbitrary values. |
| 79 | +* **Communicate with affected teams.** Work with teams to optimize their API usage through techniques like request batching, response caching, and conditional requests. |
| 80 | + |
| 81 | +## Step 5: Reduce limits and maintain over time |
| 82 | + |
| 83 | +Once you have a clear picture of your API usage, gradually reduce the rate limit to align with your instance's capacity and actual usage patterns. Monitor for unintended disruptions after each adjustment. |
| 84 | + |
| 85 | +As you refine limits, work with teams whose integrations are affected. Techniques like request batching, response caching, and conditional requests can help teams reduce their API usage. You can also exempt specific users from rate limits using the `ghe-config` utility. For more information, see [AUTOTITLE](/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities#ghe-config). |
| 86 | + |
| 87 | +Review your rate limit data periodically, since usage patterns change as new integrations are added and workflows evolve. |
| 88 | + |
| 89 | +## Additional considerations |
| 90 | + |
| 91 | +* **GraphQL API limits.** The GraphQL API has a separate rate limit (default: 5,000 points per hour) that cannot be bypassed through the exemption list. For more information, see [AUTOTITLE](/graphql/overview/rate-limits-and-node-limits-for-the-graphql-api). |
| 92 | +* **Secondary rate limits.** You can also enable secondary rate limits to protect the overall level of service. For more information, see [AUTOTITLE](/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-rate-limits#enabling-secondary-rate-limits). |
| 93 | + |
| 94 | +## Further reading |
| 95 | + |
| 96 | +* [AUTOTITLE](/rest/overview/rate-limits-for-the-rest-api) |
0 commit comments