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

# Rate Limits & Credits

> Credit-based rate limiting, plans, endpoint costs, and usage tracking

The Appeeky API uses a **credit-based** rate limiting system. Each plan has monthly allowances for normal API work and, on eligible plans, dedicated AI Visibility and creative buckets. Every API call deducts credits from the bucket that matches the endpoint's cost profile.

***

## Plans

| Plan           | Plan ID  | API credits | Creative credits | Price (monthly) | Price (yearly) | Best for                               |
| -------------- | -------- | ----------: | ---------------: | --------------- | -------------- | -------------------------------------- |
| **Indie**      | `indie`  |       5,000 |               10 | \$9/mo          | \$90/yr        | Solo developers and side projects      |
| **Starter**    | `small`  |      10,000 |               40 | \$19/mo         | \$190/yr       | Small applications and research        |
| **Growth**     | `growth` |      50,000 |              120 | \$39/mo         | \$390/yr       | Scaling teams and production workloads |
| **Pro**        | `medium` |     100,000 |              250 | \$69/mo         | \$690/yr       | Production services                    |
| **Enterprise** | `large`  |   1,000,000 |              500 | \$149/mo        | \$1,490/yr     | High-volume commercial use             |

`X-Plan` and `/v1/auth/usage` report your **Plan ID** (`indie`, `small`, `growth`, `medium`, or `large`). Web subscription bundles use `web_indie`, `web_startup`, and `web_agentic_scale`; each includes 1,000 API credits plus its plan-specific creative quota.

<Tip>
  Need more credits? Contact us at **[support@appeeky.com](mailto:support@appeeky.com)** to upgrade your plan or discuss custom pricing for higher volumes.
</Tip>

***

## Credit Costs Per Endpoint

Credits are charged based on the computational cost of each endpoint. Heavier endpoints that aggregate multiple data sources cost more. Dedicated buckets are used for AI Visibility (`credits.aiVisibility`) and creative generation (`credits.creative`).

### Free (0 credits)

| Endpoint         | Credits | Description                        |
| ---------------- | ------- | ---------------------------------- |
| `GET /v1/health` | 0       | Service health check — always free |

### Light (1 credit)

| Endpoint                       | Credits | Description                           |
| ------------------------------ | ------- | ------------------------------------- |
| `GET /v1/search`               | 1       | Search apps by keyword or App ID      |
| `POST /v1/keywords/track`      | 1       | Add keyword to your tracking list     |
| `GET /v1/keywords/suggestions` | 1       | Apple Search autocomplete suggestions |
| `GET /v1/categories`           | 1       | List all App Store categories         |

### Standard (2 credits)

| Endpoint                           | Credits | Description                         |
| ---------------------------------- | ------- | ----------------------------------- |
| `GET /v1/categories/:id/top`       | 2       | Top charts for a category           |
| `GET /v1/apps/:id`                 | 2       | Full app metadata (iTunes Lookup)   |
| `GET /v1/apps/:id/reviews`         | 2       | User reviews (Apple RSS feed)       |
| `GET /v1/apps/:id/screenshots`     | 2       | App screenshots by device type      |
| `GET /v1/keywords/ranks`           | 2       | Apps ranking for a specific keyword |
| `GET /v1/keywords/metrics`         | 2       | Search volume and difficulty scores |
| `GET /v1/apps/:id/keywords/trends` | 2       | Historical rank trend for a keyword |
| `GET /v1/new-releases`             | 2       | Recently released apps              |
| `GET /v1/discover`                 | 2       | Trending and noteworthy apps        |
| `GET /v1/discover/new-number-1`    | 2       | Apps that just reached #1           |

### Heavy (3 credits)

| Endpoint                                   | Credits | Description                                  |
| ------------------------------------------ | ------- | -------------------------------------------- |
| `GET /v1/apps/:id/keywords`                | 3       | All keyword rankings for an app              |
| `GET /v1/keywords/compare`                 | 3       | Competitor keyword overlap analysis          |
| `GET /v1/keywords/visibility`              | 3       | App visibility score across tracked keywords |
| `GET /v1/keywords/movers`                  | 3       | Per-app keyword rank gainers / losers        |
| `GET /v1/apps/:id/country-rankings`        | 3       | Chart positions across countries             |
| `GET /v1/apps/:id/screenshots/competitors` | 3       | Competitor screenshot comparison             |
| `GET /v1/categories/:id/top/screenshots`   | 3       | Screenshots for top apps in a category       |

### Advanced (4 credits)

| Endpoint                           | Credits | Description                                    |
| ---------------------------------- | ------- | ---------------------------------------------- |
| `GET /v1/keywords/compare-cluster` | 4       | Multi-competitor keyword lifecycle buckets     |
| `GET /v1/keywords/gap`             | 4       | Top opportunity-ranked competitor keyword gaps |

### Premium (5 credits)

| Endpoint                        | Credits | Description                                                   |
| ------------------------------- | ------- | ------------------------------------------------------------- |
| `GET /v1/apps/:id/intelligence` | 5       | Full intelligence report: revenue, downloads, IAPs, sentiment |

### Standard (2 credits) — continued

| Endpoint                   | Credits | Description                                   |
| -------------------------- | ------- | --------------------------------------------- |
| `GET /v1/apps/:id/similar` | 2       | Similar and competing apps (3-layer matching) |

<Note>
  Credits are only deducted on **successful** responses (2xx status codes). Failed requests (4xx, 5xx) do **not** consume credits.
</Note>

### Creative credits

| Endpoint                                                                              | Bucket   |                          Credits | Description                                       |
| ------------------------------------------------------------------------------------- | -------- | -------------------------------: | ------------------------------------------------- |
| `POST /v1/app-ad-creatives/generate` with `mode: "analyze"` or `generateImage: false` | API      |                                1 | Listing analysis and paste-ready copy only        |
| `POST /v1/app-ad-creatives/generate` with platform-funded image generation or editing | Creative | `low`: 1, `medium`: 2, `high`: 5 | Generate or edit one square image creative        |
| `POST /v1/app-ad-creatives/generate` with `X-OpenAI-Key`                              | API      |                                1 | BYOK image job; does not consume creative credits |

***

## Response Headers

Every authenticated response includes rate limit headers so you can track consumption programmatically:

| Header                     | Description                                                     | Example      |
| -------------------------- | --------------------------------------------------------------- | ------------ |
| `X-RateLimit-Limit`        | General API monthly credits for your plan                       | `5000`       |
| `X-RateLimit-Remaining`    | General API credits remaining this month                        | `4995`       |
| `X-RateLimit-Reset`        | Unix timestamp when credits reset (first of next month)         | `1743465600` |
| `X-Credit-Cost`            | Credits consumed by this request                                | `2`          |
| `X-Credit-Category`        | Bucket charged for this request                                 | `general`    |
| `X-AiVisibility-Limit`     | Monthly AI Visibility bucket limit                              | `3000`       |
| `X-AiVisibility-Remaining` | AI Visibility credits remaining when the route uses that bucket | `2991`       |
| `X-Creative-Limit`         | Monthly creative bucket limit                                   | `10`         |
| `X-Creative-Remaining`     | Creative credits remaining when the route uses that bucket      | `8`          |
| `X-Plan`                   | Your current plan identifier                                    | `indie`      |

**Example response headers:**

```
HTTP/2 200
Content-Type: application/json
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4993
X-RateLimit-Reset: 1743465600
X-Credit-Cost: 2
X-Credit-Category: general
X-Creative-Limit: 10
X-Plan: indie
```

<Tip>
  Use `X-RateLimit-Remaining` in your code to implement graceful throttling before hitting the limit.
</Tip>

***

## Check Your Usage

Use the usage endpoint to see a detailed breakdown of your current month's consumption:

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/auth/usage" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch("https://api.appeeky.com/v1/auth/usage", {
    headers: { "X-API-Key": "YOUR_API_KEY" },
  });
  const { data } = await res.json();

  console.log(`Plan: ${data.plan}`);
  console.log(`Used: ${data.used} / ${data.monthlyCredits}`);
  console.log(`Remaining: ${data.remaining}`);
  console.log(`Resets: ${data.resetDate}`);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.get(
      "https://api.appeeky.com/v1/auth/usage",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]

  print(f'Plan: {data["plan"]}')
  print(f'Used: {data["used"]} / {data["monthlyCredits"]}')
  print(f'Remaining: {data["remaining"]}')
  print(f'Resets: {data["resetDate"]}')
  ```
</CodeGroup>

**Response (200 OK):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "plan": "indie",
    "monthlyCredits": 5000,
    "used": 127,
    "remaining": 4873,
    "resetDate": "2026-03-01T00:00:00.000Z",
    "credits": {
      "general": { "limit": 5000, "used": 127, "remaining": 4873 },
      "aiVisibility": { "limit": 3000, "used": 0, "remaining": 3000 },
      "creative": { "limit": 10, "used": 0, "remaining": 10 },
      "resetDate": "2026-03-01T00:00:00.000Z"
    },
    "usageByEndpoint": [
      { "endpoint": "GET /apps/:id", "totalCredits": 40, "requestCount": 20 },
      { "endpoint": "GET /apps/:id/intelligence", "totalCredits": 50, "requestCount": 10 },
      { "endpoint": "GET /keywords/ranks", "totalCredits": 20, "requestCount": 10 },
      { "endpoint": "GET /search", "totalCredits": 12, "requestCount": 12 },
      { "endpoint": "GET /apps/:id/keywords", "totalCredits": 3, "requestCount": 1 },
      { "endpoint": "POST /keywords/track", "totalCredits": 2, "requestCount": 2 }
    ]
  }
}
```

| Field                  | Type   | Description                                                                                                                      |
| ---------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `plan`                 | string | Current plan id: `indie`, `small`, `growth`, `medium`, `large`, or web bundles `web_indie` / `web_startup` / `web_agentic_scale` |
| `monthlyCredits`       | number | General API credits for the billing period                                                                                       |
| `used`                 | number | Total credits consumed across all buckets, kept for backward compatibility                                                       |
| `remaining`            | number | General API credits left until reset                                                                                             |
| `credits.general`      | object | General API bucket limit, used, and remaining                                                                                    |
| `credits.aiVisibility` | object | Dedicated AI Visibility bucket limit, used, and remaining                                                                        |
| `credits.creative`     | object | Dedicated creative bucket limit, used, and remaining                                                                             |
| `resetDate`            | string | ISO 8601 date when credits reset                                                                                                 |
| `usageByEndpoint`      | array  | Breakdown by endpoint with credit totals and request counts                                                                      |

***

## When the Limit Is Reached

When your monthly credits are exhausted, all credit-consuming endpoints return **429 Too Many Requests**:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Monthly credit limit reached (5000/5000). Upgrade plan for more credits."
  }
}
```

The response still includes rate limit headers so you can check the reset time:

```
HTTP/2 429
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743465600
X-Plan: indie
```

<Warning>
  The `/v1/health` endpoint (0 credits) always works, even when your credit limit is exhausted. Use it to verify the service is up before investigating 429 errors.
</Warning>

***

## Monthly Reset

Credits reset automatically on the **first day of each calendar month** at **00:00 UTC**. Unused credits do **not** carry over to the next month.

| Event         | Timing                                                |
| ------------- | ----------------------------------------------------- |
| Credit reset  | 1st of each month, 00:00 UTC                          |
| Carry-over    | No — unused credits expire                            |
| Billing cycle | Calendar month                                        |
| Plan changes  | Take effect immediately; new credit allowance applies |

<Tip>
  Check your `X-RateLimit-Reset` response header or the `resetDate` field from `/v1/auth/usage` to see the exact reset timestamp for your current billing period.
</Tip>