> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo Rate Limiting

> Guide to GitHub API rate limits, checking usage, authenticating to increase limits, avoiding throttling, and examples for querying limits, fetching contents, and listing workflow runs.

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.](https://mintcdn.com/kodekloud-c4ac6d9a/TlnHw4JjIHBx3Cta/images/GitHub-Administration-Certification/Monitoring-and-Optimization/Demo-Rate-Limiting/github-docs-rest-api-rate-limits.jpg?fit=max\&auto=format\&n=TlnHw4JjIHBx3Cta\&q=85\&s=a9d26754622dc7e2ecdc3532921ee616)

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.](https://mintcdn.com/kodekloud-c4ac6d9a/TlnHw4JjIHBx3Cta/images/GitHub-Administration-Certification/Monitoring-and-Optimization/Demo-Rate-Limiting/github-docs-secondary-rate-limits-screenshot.jpg?fit=max\&auto=format\&n=TlnHw4JjIHBx3Cta\&q=85\&s=f8c71db3ccc29fcd9c53f989cfa57f63)

## 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:

```bash theme={null}
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):

```json theme={null}
{
  "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):

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}
```

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

```json theme={null}
{
  "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:

```bash theme={null}
echo "IyB0ZXN0LXNlY3JldA==" | base64 -d
# Output:
# test-secret
```

## Using the Actions REST API — listing workflow runs

To list workflow runs for a repository:

```bash theme={null}
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:

```json theme={null}
{
  "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.

## Links and references

* [GitHub REST API — Rate limit documentation](https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting)
* [About secondary rate limits](https://docs.github.com/rest/overview/resources-in-the-rest-api#secondary-rate-limits)
* [Authenticating to a GitHub organization with SAML single sign-on](https://docs.github.com/articles/authenticating-to-a-github-organization-with-saml-single-sign-on/)

> [card] [Watch Video](https://learn.kodekloud.com/user/courses/github-administration-certification/module/ddb3d739-d57f-4374-b851-69bb14cbeb8b/lesson/0ef374bb-3389-4651-bfbc-e3157671c1a6)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.