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

# Billing & Credits

> Understand wallet credits, metered API behavior, credit headers, and subscription-included API families.

## Credit System

<Info>
  Current prices, wallet top-ups, and subscription options live on the
  [pricing page](https://jobo.world/pricing) and in the
  [dashboard](https://enterprise.jobo.world/credits).
</Info>

Credits are the wallet unit used by metered API calls. When a metered request
succeeds, the API deducts the applicable credits from your wallet and returns
headers you can use for logging, budget alerts, or usage reconciliation.

## Metered Endpoints

These endpoint families can consume wallet credits depending on your plan:

<CardGroup cols={3}>
  <Card title="Jobs Search" icon="magnifying-glass">
    Full-text and advanced search across job listings. Search-style endpoints
    meter by delivered results, so a request that returns fewer records than the
    requested page size only bills for what was delivered.

    `GET /api/jobs` + `POST /api/jobs/search` + `GET /api/companies/{id}/jobs`
  </Card>

  <Card title="Jobs Feed" icon="rss">
    Cursor-paginated streams for high-volume job sync. Feed subscriptions can
    include this API family without wallet debits; pay-as-you-go access is
    metered by delivered results.

    `POST /api/jobs/feed`
  </Card>

  <Card title="Geocode" icon="location-dot">
    Convert raw location strings into structured city, region, country, and
    coordinate data. Geocoding is a flat metered lookup.

    `GET /api/locations/geocode`
  </Card>
</CardGroup>

<Note>
  Search, Feed, and the Companies list-jobs endpoint perform a balance precheck
  against the request size and debit the actual delivered quantity after the
  response is built. Flat metered endpoints debit before work begins. Failed
  `4xx` / `5xx` responses do not deduct credits.
</Note>

## Unmetered Endpoints

These endpoints do not deduct wallet credits:

| Endpoint                                              | Notes                                                                                       |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `GET /api/jobs/expired`                               | Designed to keep downstream inventories clean. The request still counts toward rate limits. |
| `POST /api/jobs/feed` *(with Jobs Feed subscription)* | Wallet debits are waived for subscription holders.                                          |
| `GET /api/jobs/{id}`                                  | Single job lookup by ID. The request still counts toward rate limits.                       |
| `GET /api/companies/{id}`                             | Public company profile lookup. No API key is required.                                      |

## Currently Unavailable

| Endpoint            | Status                                                                        |
| ------------------- | ----------------------------------------------------------------------------- |
| `/api/auto-apply/*` | Temporarily disabled. Requests return `503 Service Unavailable` while paused. |

## Request Flow

Every metered API request goes through this pipeline before a response is returned:

<Steps>
  <Step title="Authenticate">
    The API validates your `X-Api-Key` header when the endpoint requires one. If
    the key is missing or invalid, you receive **401 Unauthorized** and no wallet
    activity occurs.
  </Step>

  <Step title="Rate Limit Check">
    Your request is checked against the rate-limit windows for your plan. If a
    window is exhausted, you receive **429 Too Many Requests** with a
    `Retry-After` header. No credits are deducted on rate-limited requests.
  </Step>

  <Step title="Wallet Check">
    Metered endpoints verify that your wallet can cover the request before work
    begins. If the balance is insufficient, you receive **402 Payment Required**
    with `X-Credits-Required` and `X-Credits-Balance`.
  </Step>

  <Step title="Debit and Response">
    When a wallet debit occurs, the response includes `X-Credits-Deducted` and
    `X-Credits-Balance`. Unmetered responses and zero-debit responses may omit
    credit headers.
  </Step>
</Steps>

## Credit Response Headers

Credit headers appear only when wallet metering is relevant to the response:

| Header               | When Returned     | Description                                             |
| -------------------- | ----------------- | ------------------------------------------------------- |
| `X-Credits-Deducted` | wallet debit      | Credits consumed by this specific request.              |
| `X-Credits-Balance`  | wallet debit, 402 | Your wallet balance after the debit or failed precheck. |
| `X-Credits-Required` | 402 only          | Credits the request would have needed to succeed.       |

### Successful Metered Request

```http theme={null}
HTTP/1.1 200 OK
X-Credits-Deducted: <credits_used>
X-Credits-Balance: <remaining_balance>
Content-Type: application/json
```

### Insufficient Credits

```http theme={null}
HTTP/1.1 402 Payment Required
X-Credits-Required: <credits_needed>
X-Credits-Balance: <current_balance>
Content-Type: application/json
```

```json theme={null}
{
  "error": "Insufficient credits",
  "credits_required": 123,
  "credits_balance": 45
}
```

Add credits in the [dashboard](https://enterprise.jobo.world/credits), then retry
the request.

## FAQ

<AccordionGroup>
  <Accordion title="Where do I see current prices?">
    Use [jobo.world/pricing](https://jobo.world/pricing) for public pricing and
    the [dashboard](https://enterprise.jobo.world/credits) for your wallet,
    subscription, and billing status.
  </Accordion>

  <Accordion title="What happens when I run out of credits?">
    Metered endpoints return **HTTP 402 Payment Required**. The response includes
    `X-Credits-Required` and `X-Credits-Balance` so you can decide whether to
    add credits and retry.
  </Accordion>

  <Accordion title="Are credits deducted on failed requests?">
    No. Credits are only deducted when a metered request successfully completes
    and produces billable work. Rate limits, validation errors, authentication
    failures, and server errors do not deduct credits.
  </Accordion>

  <Accordion title="Are there rate limits in addition to credits?">
    Yes. Rate limits apply per minute, per hour, and per day to protect service
    quality. Credits are deducted only after rate-limit checks pass. See the
    [Rate Limits](/resources/rate-limits) page for details.
  </Accordion>

  <Accordion title="Do subscription endpoints also use wallet credits?">
    Some subscriptions include specific API families without wallet debits. If
    an endpoint is included with your subscription, the API can still apply rate
    limits, but wallet credit headers may be absent because no debit occurred.
  </Accordion>

  <Accordion title="Can I set up budget alerts?">
    Use the [dashboard](https://enterprise.jobo.world/credits) to review wallet
    and billing settings. You can also monitor spend programmatically by reading
    `X-Credits-Deducted` and `X-Credits-Balance` on metered responses.
  </Accordion>
</AccordionGroup>