> ## 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 and metering

> How wallet credits are consumed, which endpoints are free, and what happens when your balance runs out.

## 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={2}>
  <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>

  <Card title="Auto Apply" icon="bolt">
    **Coming soon.** The profileless, callback-driven API is not available in
    beta or production. Pricing and quotas will be published before launch.

    `POST /api/auto-apply/applications`
  </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, and that
  debit is automatically refunded whenever the request ends in a `4xx` / `5xx`
  response — you only ever pay for calls that succeed.
</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.                                          |
| `POST /api/jobs/feed/managed` *(with Jobs Feed subscription)* | Same metering as the main feed — 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.                                      |

## Auto Apply availability

Auto Apply is a contract preview only. There is no allowlisted beta or live
application intake today. Create is deployment-gated and currently returns
HTTP `503` with problem code `auto_apply_coming_soon`; no usage is billed.

## 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 headers accompany every metered response. See [Response headers](/docs/response-headers) for the full inventory and exactly when each one appears.

## 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](/docs/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>