Monitoring API Rate Limits

An audit log tells you who did what. Monitoring your API usage tells you how your automated integrations behave and whether they threaten platform stability.

A presentation slide titled "Why API Usage Needs Watching" showing two panels: an "Audit log" with user actions (e.g., protected_branch.destroy, org.add_member, repo.change_visibility). The right panel shows "API usage" counts for bots/services: deploy-bot 4,873, jira-sync 1,204, and security-scanner 312.

Every API call to your enterprise counts toward rate limits. As an administrator, you should monitor limits, find bottlenecks, and ensure teams use the most efficient integration pathways. Why this matters

Prevent unexpected outages or failed automation from exceeded quotas.
Improve CI/CD reliability by reducing throttling and retries.
Allocate improvements (migrate to GitHub Apps, add caching) where they’ll have the biggest impact.

Authentication types and typical capacity

Authentication method	Approx. throughput	When to use
Personal Access Token (PAT)	5,000 requests/hour	Simple scripts and low-volume automation
GitHub App installation	15,000 requests/hour	Heavy CI/CD, enterprise integrations (recommended for scale)
Unauthenticated requests	60 requests/hour	Browsing public endpoints or very low-volume tools

Understanding rate-limit headers Every API response contains headers that tell you where you stand in real time. Monitor these fields to make informed decisions without issuing extra API calls.

Header	Meaning
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Used`	Requests consumed in this window
`X-RateLimit-Reset`	UTC epoch seconds when the window resets
`X-RateLimit-Resource`	Resource category counted against (e.g., `core`, `search`)

Example: an authenticated curl request and the rate-limit headers it returns

$ curl -i -H "Authorization: Bearer $PAT" https://api.github.com/orgs/acme/repos

HTTP/2 200
server: github.com
content-type: application/json; charset=utf-8
x-github-request-id: 8C4A:2F1B:1D0E7A:3B44F1
x-ratelimit-limit: 5000
x-ratelimit-remaining: 127
x-ratelimit-used: 4873
x-ratelimit-reset: 1735689600
x-ratelimit-resource: core

Use the GET /rate_limit endpoint sparingly to inspect usage programmatically. It does not consume your primary quota, but avoid abusive polling to prevent triggering secondary throttling.

You can safely poll GET /rate_limit to inspect usage without eating into your main quota, but avoid extreme polling rates to prevent hitting secondary rate limits.

REST vs GraphQL: different models

REST API: simple request-count model (requests per time window).
GraphQL API: point-based cost model. You have a 5,000-point-per-hour budget; cost depends on query complexity rather than raw request count.

GraphQL cost considerations

Small queries often cost 1 point.
Complex, deeply nested queries can cost hundreds of points.
A single well-designed GraphQL query can be more efficient than many REST calls, but an unoptimized one can exhaust points quickly.

Example GraphQL queries

# Light query — typically low cost
{
  organization(login: "acme") {
    membersWithRole(first: 10) { nodes { login name } }
  }
}

# Heavy query — can be costly if not paginated/limited
{
  organization(login: "acme") {
    repositories(first: 100) {
      nodes {
        issues(first: 100) { nodes { title } }
        pullRequests(first: 100) { nodes { title } }
      }
    }
  }
}

Monitor the cost returned by GraphQL responses and paginate or split large requests when necessary. Secondary rate limits (burst/concurrency protection) Even within hourly quotas, GitHub enforces secondary rate limits to prevent bursts, high concurrency, or abusive polling. Secondary limits protect platform health and apply dynamically.

A dashboard titled "The Second Gatekeeper" showing a progress bar (1,204 / 5,000 requests used) with the status "Well within budget" and buttons labeled "Secondary rate limits" and "Rapid concurrency."

When secondary limits trigger, the API returns HTTP 429 Too Many Requests and includes a Retry-After header. Your integrations must handle 429 responses gracefully using exponential backoff (ideally with jitter) and by reducing concurrency. Example: high concurrency producing 429 responses

# Simulate many concurrent requests
$ xargs -P 100 -n 1 curl -s -o /dev/null -w "%{http_code} " < urls.txt
200 200 200 200 200 429 429 429 429 429 429 429 429 429 429 429 429 429 429 429 429

Example: a single request hitting a secondary limit

$ curl -i $API/repos/acme/api/issues

HTTP/2 429
retry-after: 60
x-ratelimit-remaining: 3796

Implement retry behavior like this (conceptual):

$ python retry_with_backoff.py
attempt 1  429  sleep 1s
attempt 2  429  sleep 2s
attempt 3  429  sleep 4s
attempt 4  429  sleep 8s
attempt 5  200  ok

Secondary rate limits are not resolved by increasing hourly quotas alone. Implement exponential backoff with jitter and reduce concurrency to avoid repeated 429s and protect platform stability.

Operational guidance for administrators

Monitor usage per integration
- Identify integrations consistently using >80% of their hourly quota and prioritize them for optimization.
Prefer GitHub Apps for heavy automation
- Migrate tools that frequently get 403/429 from PATs to GitHub App installations to gain higher capacity.
Enforce best practices in CI/CD and tooling
- Batch requests, cache results, and paginate large responses.
- Use GraphQL efficiently (limit fields and depth) when appropriate.
Implement resilient retry strategies
- Exponential backoff with jitter and respect Retry-After.
- Reduce concurrency (throttle workers or queue tasks) rather than reissuing requests immediately.
Audit and enforce at scale
- Use monitoring dashboards and alerts for integrations that spike usage or generate repeated 429/403 responses.

Summary By monitoring rate-limit headers, using GET /rate_limit judiciously, optimizing GraphQL queries, and handling secondary limits with backoff and reduced concurrency, you can keep integrations reliable without destabilizing the platform. Links and references

Course Introduction

Foundation Setup

Identity and Access Management

Governance and Roles

Security and Compliance

GitHub Actions and Runners

Administration and Support

Monitoring and Optimization

Monitoring API Rate Limits

Watch Video