# Plans, Limits & Upgrades

## Plans & Quotas
To use this API you need to subscribe to a plan. Plans are valued on the number of new jobs per month. Some plans have additional features as well, we will lay these out below.

Each plan comes with a number of 'Jobs' and 'API Requests'.<br/>
**'Jobs' quota is credited towards the number of jobs returned by the 'New Jobs' endpoints `active-ats` and `active-jb`.** <br/> For example, if your request returns 5 jobs, your 'Jobs' credit will be deducated by 5.
Other endpoints are not credited towards 'Jobs', these are complimentary to your plan. For example `modified-ats` and the expired jobs endpoints.

:::note{title="Preventing Duplicate Jobs"}

To prevent retrieving duplicate jobs from our endpoints and overspending on credits, please make sure to request our API on a recurring basis depending on your chosen `time_frame` parameter:

- **`1h`**: Request every hour
- **`24h`**: Request during the same hour every day

:::



**'API Requests' quota is credited for each API call.** Most plans have half the number of 'API Requests' compared to the number of 'Jobs'. <br/>
There's a hard limit for 'API Requests' whereas 'Jobs' has overages.

### Overages
Some plans allow you to make additional requests once you hit your quota. These requests are priced on a 'per job' level. You will be charged an additional fee per job once you hit your quota

### Plans with additional features

## Upgrades
At any point during your subscription you can upgrade to a plan with higher limits. When you upgrade, a prorated credit is applied toward your new plan and you can start using it immediately.

To calculate the credit, the system looks at the **largest** of the following three values:

- **Time elapsed** in the current billing period
- **`Jobs` quota consumed** so far in the current period
- **`API Requests` quota consumed** so far in the current period

Whichever is highest is treated as the "used" portion of your current plan, and the remainder of the plan price is credited toward the upgrade.

**Example:** A customer on **Starter** ($95/month — 20,000 Jobs, 10,000 API Requests) upgrades to **Pro 50k** ($175/month — 50,000 Jobs, 25,000 API Requests) on day 15 of a 30-day billing period.

| Factor | Usage | Percentage |
| --- | --- | --- |
| Time elapsed | 15 / 30 days | 50% |
| `Jobs` consumed | 14,000 / 20,000 | 70% |
| `API Requests` consumed | 5,500 / 10,000 | 55% |
| **Max of the three** | — | **70%** |
| **Credit applied** | (1 − 70%) × $95 | **$28.50** |

In this example the `Jobs` meter is the deciding factor — it has been consumed faster than both time and the `API Requests` meter, so the customer is credited for the remaining 30% of their Starter plan.

The credit is applied once and is not carried forward to future billing cycles.

## Universal Rate Limit
Each plan is limited to 600 requests per minute

## Tracking Credit Usage
There are two ways to track your credit usage:

### Headers: 
Every successful response includes a set of `x-api-*` headers so you can track usage in real time. The headers reflect your balance **after** the current request has been metered, so you can use them directly for client-side budgeting.

| Header | Description |
| --- | --- |
| `x-api-jobs-this-request` | Number of `Jobs` credits this single request consumed. Always `0` on endpoints that don't consume `Jobs` credits (e.g. `modified-ats`, expired jobs, organizations). |
| `x-api-jobs-remaining` | `Jobs` credits left in your plan for the current period. |
| `x-api-jobs-limit` | Total `Jobs` allowance included in your plan for the current period. |
| `x-api-requests-remaining` | `API Requests` credits left in your plan for the current period. |
| `x-api-requests-limit` | Total `API Requests` allowance included in your plan for the current period. |

Example response headers:

```http
x-api-jobs-this-request: 5
x-api-jobs-remaining: 9450
x-api-jobs-limit: 10000
x-api-requests-remaining: 4823
x-api-requests-limit: 5000
```

:::warning{title="Caching of quota"}

Quota headers are cached for a few seconds after each request. If you make several calls in quick succession, the `remaining` values may not yet reflect the credits consumed by the most recent requests. For accurate budgeting, allow a short delay between calls or rely on the `x-api-jobs-this-request` header (which is always exact for the current response) to track usage locally.

:::

**Dashboard**:
You can also see your current en remaining credits on the [https://developer.fantastic.jobs/subscriptions](user dashboard)