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

# Historical Jobs Export

> Buy a full-record export of the historical archive for a filter set, priced per record

<Warning>
  **Rolling out.** The Historical Jobs endpoints are documented ahead of release and may not be live on `api.hirebase.org` yet. If you get a `404` or `405`, the rollout has not reached production; check the [changelog](/docs/changelog) or email [hello@hirebase.org](mailto:hello@hirebase.org) and we will let you know when it is available.
</Warning>

Export every archived job matching a filter set as a downloadable file. Pass the **same filters** you refined with [Historical Jobs Search](/docs/api-reference/jobs/historical-search); the export bills exactly the count that endpoint showed.

Historical exports are **purchased per dataset**, not drawn from your monthly Jobs allowance. The response contains a Stripe Checkout link and the id of the task the export will run under. Nothing runs, and nothing is charged, until payment completes.

<Warning>
  This endpoint requires an API key. See [Authentication](/docs/authentication).
</Warning>

## Pricing

The price is a function of the number of records, quoted before you pay and never higher than the quote.

| Records        | Price per record |
| -------------- | ---------------- |
| First 1,000    | \$0.12           |
| Next 9,000     | \$0.03           |
| Next 90,000    | \$0.01           |
| Beyond 100,000 | \$0.001          |

Minimum charge $0.50. Examples: 500 records → $60; 3,096 records → $182.88; 20,000 records → $490; 150,000 records → \$1,340.

If the export fails after payment, the charge is refunded automatically.

## Request Body

<ParamField body="search" type="object" required>
  The filter set. Same fields and rules as [Historical Jobs Search](/docs/api-reference/jobs/historical-search): `job_titles`, `keywords`, `geo_locations`, `location_group`, `company_names`, `company_slugs`, `date_posted_from`, `date_posted_to`, `date_expired_from`, `date_expired_to`. At least one filter is required; unknown keys return `422`.
</ParamField>

<ParamField body="format" type="string" default="json">
  `json` (JSON Lines: one record per line) or `csv`.
</ParamField>

<ParamField body="limit" type="integer">
  Cap the export at this many records, most recently posted first. Omit to export every match. Priced at `min(limit, match count)`.
</ParamField>

<ParamField body="redirect_to" type="string">
  Where to send the buyer after Checkout. Defaults to the [historical jobs guide](/docs/guides/historical-jobs).
</ParamField>

## Response

<ResponseField name="task_id" type="string">
  The task the export runs under once paid. Poll [`GET /v2/tasks/{task_id}`](/docs/api-reference/tasks/get-task-status); it returns `404` until payment completes.
</ResponseField>

<ResponseField name="checkout_url" type="string">
  Stripe Checkout URL. Open it (or send it to whoever holds the card) to pay.
</ResponseField>

<ResponseField name="record_count" type="integer">
  Records the export will contain.
</ResponseField>

<ResponseField name="price_usd" type="number">
  Total price in USD.
</ResponseField>

<ResponseField name="status" type="string">
  Always `awaiting_payment` at this point.
</ResponseField>

## After payment

The export task is created immediately on payment. When it finishes, the task's `result` carries `download_url` (private link, valid 30 days), `file_size` and `record_count`, and an email with the same link goes to your account address.

## Exported record fields

Each record is the full archived job object: `_id`, `job_title`, `job_title_raw`, `company_name`, `company_slug`, `company_data`, `locations`, `location_type`, `date_posted`, `date_expired`, `job_categories`, `job_type`, `experience_level`, `yoe_range`, `salary_range`, `skills`, `technologies`, `benefits`, `education_level`, `requirements_summary`, `visa_sponsored`, `application_link`, `job_board`, `md5_hash`, and `description` where still retained (see the coverage table on the search page).

<Note>
  Multi-location postings appear once per location. To collapse them, group on `company_slug` + `job_title` + `date_posted` (or on `md5_hash`) on your side.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.hirebase.org/v2/jobs/historical/export' \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "search": {
        "job_titles": ["sustainability", "ESG", "climate", "renewable"],
        "geo_locations": [{"country": "United States"}],
        "date_posted_from": "2023-01-01"
      },
      "format": "csv"
    }'
  ```

  ```python Python theme={null}
  import hirebase

  client = hirebase.Client(api_key="YOUR_API_KEY")
  filters = {
      "job_titles": ["sustainability", "ESG", "climate", "renewable"],
      "geo_locations": [{"country": "United States"}],
      "date_posted_from": "2023-01-01",
  }
  order = client.jobs.historical_export(filters, format="csv")
  print(order["record_count"], order["price_usd"], order["checkout_url"])

  # ... pay at checkout_url, then:
  success, result = client.tasks.poll(order["task_id"], timeout=1800)
  print(result["download_url"] if success else result)
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "task_id": "1f0c7a4e-6b3e-4a3f-9d2b-8f4c1e2d3a4b",
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
    "record_count": 3096,
    "price_usd": 182.88,
    "currency": "usd",
    "status": "awaiting_payment",
    "format": "csv",
    "note": "Complete payment at checkout_url to start the export. The task is created on payment; poll GET /v2/tasks/{task_id} or wait for the email with the download link (valid 30 days)."
  }
  ```

  ```json 400 theme={null}
  { "detail": "No archived jobs match these filters. Use /v2/jobs/historical/search to refine." }
  ```
</ResponseExample>