Demo Rate Limiting

This guide explains GitHub API rate limiting: what limits exist, how to check your current usage, and tips to avoid throttling. It covers both primary and secondary limits, how to authenticate to raise limits, and example API calls (with curl) for checking limits, reading repository contents, and listing Actions workflow runs. GitHub enforces two classes of rate limits: primary and secondary. Primary rate limits define how many requests a client (by IP, app, or user) can make over a time window:

Unauthenticated requests (no token): 60 requests per hour (attributed to the originating IP).
Authenticated requests using a personal access token (PAT): 5,000 requests per hour (per user/token).
GitHub Apps: higher limits (example: ~15,000 requests per hour depending on context).

A dark-themed screenshot of the GitHub Docs site showing REST API documentation about rate limits. The left sidebar navigation is visible and the main content explains primary rate limits for authenticated and unauthenticated users.

Secondary rate limits protect GitHub’s availability by detecting abusive or excessive usage patterns. These can be triggered by many concurrent requests, bursts of expensive operations, or too many requests per minute and are enforced even if you are within the primary limit.

A dark‑mode screenshot of the GitHub Docs page titled "About secondary rate limits," showing the left navigation menu and the main article text describing API rate limit rules and limits.

Quick reference — primary limits

Client type	Typical limit	Notes
Unauthenticated (IP-based)	`60` requests/hour	Applies when no token is used.
Authenticated (PAT)	`5,000` requests/hour	Per user/token for core resources.
GitHub Apps	Varies (e.g., ~`15,000`/hour)	Depends on app installation context.

How to check your current rate limit

Rate limits are returned in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Reset, and X-RateLimit-Resource.
You can also query the REST endpoint GET /rate_limit to receive the same information in JSON form.

Example: check rate limits (unauthenticated) with curl:

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/rate_limit

Example JSON response (abridged; unauthenticated):

{
  "resources": {
    "code_search": {
      "limit": 60,
      "remaining": 60,
      "reset": 1787822556,
      "used": 0
    },
    "core": {
      "limit": 60,
      "remaining": 60,
      "reset": 1787822556,
      "used": 0
    },
    "graphql": {
      "limit": 0,
      "remaining": 0,
      "reset": 0,
      "used": 0
    }
  },
  "rate": {
    "limit": 60,
    "remaining": 60,
    "reset": 1787822556,
    "used": 0
  }
}

Response headers also include the X-RateLimit-* fields so you can programmatically inspect and throttle clients or surface usage dashboards.

What each `X-RateLimit-*` header means

Header	Meaning
`X-RateLimit-Limit`	Maximum number of requests allowed in the window.
`X-RateLimit-Remaining`	How many requests remain in the current window.
`X-RateLimit-Used`	Number of requests used in window.
`X-RateLimit-Reset`	Time when the window resets (Unix epoch seconds).
`X-RateLimit-Resource`	The resource the header applies to (e.g., `core`, `search`).

Using a Personal Access Token (PAT)

Authenticate requests with a PAT to increase the core limit (commonly from 60 to 5000 per hour). Create a token in GitHub: Developer settings → Personal access tokens. Then include it in the Authorization header. Example (authenticated request):

curl --include \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/rate_limit

Replace YOUR_TOKEN with a securely stored token (do not hard-code tokens in source control or logs).

If you need access to private repository data, ensure your token has the required scopes (for example, repo). For organization repos protected by SAML single sign-on, grant your token access to the organization through your identity provider; otherwise requests will return a 403 with SAML enforcement instructions.

Fetching repository contents

To fetch a file’s contents from a repository, call the repository contents endpoint with the owner, repo, and path:

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/repos/OWNER/REPO/contents/PATH"

Notes:

Wrap placeholder values like OWNER, REPO, PATH, and YOUR_TOKEN in backticks when editing MDX.
For private repositories, omitting Authorization often returns 404 Not Found (GitHub hides the existence of private repos) or 401 Unauthorized/Bad credentials for invalid tokens.

Example error when credentials are invalid:

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}

Example successful response (abridged). The file content is Base64-encoded in the content field:

{
  "name": "README.md",
  "path": "README.md",
  "sha": "3e225b0b7ed75ed78e5a2227a3f1d80bf2952286",
  "size": 13,
  "url": "https://api.github.com/repos/sid-dev2-kk/test-secret/contents/README.md?ref=main",
  "html_url": "https://github.com/sid-dev2-kk/test-secret/blob/main/README.md",
  "git_url": "https://api.github.com/repos/sid-dev2-kk/test-secret/git/blobs/3e225b0b7ed75ed78e5a2227a3f1d80bf2952286",
  "download_url": "https://raw.githubusercontent.com/sid-dev2-kk/test-secret/main/README.md",
  "type": "file",
  "content": "IyB0ZXN0LXNlY3JldA==\n",
  "encoding": "base64",
  "_links": {
    "self": "https://api.github.com/repos/sid-dev2-kk/test-secret/contents/README.md?ref=main",
    "git": "https://api.github.com/repos/sid-dev2-kk/test-secret/git/blobs/3e225b0b7ed75ed78e5a2227a3f1d80bf2952286",
    "html": "https://github.com/sid-dev2-kk/test-secret/blob/main/README.md"
  }
}

Decode Base64 locally:

echo "IyB0ZXN0LXNlY3JldA==" | base64 -d
# Output:
# test-secret

Using the Actions REST API — listing workflow runs

To list workflow runs for a repository:

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/repos/OWNER/REPO/actions/runs"

Organization-level protections:

If your token lacks organization access (for example, SAML SSO not authorized), GitHub returns a 403 Forbidden with an explanation and instructions to grant token access.

Example SAML enforcement error:

{
  "message": "Resource protected by organization SAML enforcement. You must grant your Personal Access token access to this organization.",
  "documentation_url": "https://docs.github.com/articles/authenticating-to-a-github-organization-with-saml-single-sign-on/"
}

Best practices and next steps

Monitor usage programmatically using the X-RateLimit-* headers or the /rate_limit endpoint.
Reduce polling frequency and avoid aggressive loops.
Use conditional requests (ETags / If-None-Match) to avoid downloading unchanged resources.
Implement exponential backoff and retry on 429 Too Many Requests or secondary-rate-limit responses.
Cache common responses where feasible.
For organization data, ensure your token is authorized with appropriate scopes and SAML access if enforced.

Best practice: cache responses, use conditional requests with ETags, and implement exponential backoff on 429/secondary-rate-limit responses to reduce the likelihood of hitting secondary limits.

Course Introduction

Foundation Setup

Identity and Access Management

Governance and Roles

Security and Compliance

GitHub Actions and Runners

Administration and Support

Monitoring and Optimization

Demo Rate Limiting

Quick reference — primary limits

How to check your current rate limit

What each `X-RateLimit-*` header means

Using a Personal Access Token (PAT)

Fetching repository contents

Using the Actions REST API — listing workflow runs

Best practices and next steps

Links and references

Watch Video

​Quick reference — primary limits

​How to check your current rate limit

​What each X-RateLimit-* header means

​Using a Personal Access Token (PAT)

​Fetching repository contents

​Using the Actions REST API — listing workflow runs

​Best practices and next steps

​Links and references

Watch Video

Quick reference — primary limits

How to check your current rate limit

What each `X-RateLimit-*` header means

Using a Personal Access Token (PAT)

Fetching repository contents

Using the Actions REST API — listing workflow runs

Best practices and next steps

Links and references