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

> Research past hiring: discover what the archive holds, refine your filters for free, then buy the full dataset

<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>

The live Jobs API answers "who is hiring right now". The historical archive answers "who **was** hiring, for what, where and when". It holds every posting Hirebase has seen expire, with the same structured fields as live jobs, and is sold **by the dataset** rather than against a monthly quota.

Typical uses: labour-market research over a segment (for example US sustainability / ESG roles since 2023), backfilling a database with past postings for a set of titles or companies, market sizing and competitive analysis, and building training or evaluation corpora.

## The workflow

<Steps>
  <Step title="Discover, for free">
    Call [Historical Jobs Search](/docs/api-reference/jobs/historical-search) with your filters. You get the total match count, a breakdown by year posted, the top hiring companies, a sample of matching titles, a description-text coverage estimate and a price quote. It costs nothing, so iterate until the match set looks right.
  </Step>

  <Step title="Export, priced per record">
    Send the **same** filter object to [Historical Jobs Export](/docs/api-reference/jobs/historical-export) with `format` and an optional `limit`. The response quotes the exact price and returns a Stripe Checkout link plus the task id.
  </Step>

  <Step title="Pay, then download">
    Pay at the link. The export starts immediately, streams every matching full record to a file, and emails you a private download link valid for 30 days. You can also poll [`GET /v2/tasks/{task_id}`](/docs/api-reference/tasks/get-task-status).
  </Step>
</Steps>

## What you can filter on

Job-title terms, keywords (matched on skills, technologies and benefits), geography (country, region, city or a named region group), company names or slugs, and posted / expired date ranges. Anything else returns `422` so a typo can never silently widen a paid export. Salary, seniority, job type, industry and work arrangement are **in every exported record** but are not filterable on the archive yet.

## What you get, and what is missing

Every record keeps its structured fields: title, company, location, posted and expired dates, category, seniority, years of experience, salary, skills, technologies, benefits, education and requirements summary. Free-text `description` is retained on a subset; the search response's `coverage.description_text_sample_pct` tells you the share for your particular match set before you pay.

Coverage by year reflects Hirebase's own crawl growth. Expect a few hundred records per year before 2025 for a narrow segment and thousands from 2025 on. The `by_year_posted` breakdown shows you exactly what you would be buying.

Multi-location postings appear once per location. If you want one row per opening, group on `company_slug` + `job_title` + `date_posted` after download.

## Pricing

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

A 3,000-record dataset is about $180; 20,000 records about $490; 150,000 about \$1,340. The quote is shown before you pay and never exceeded. Failed exports are refunded automatically.

## Example

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

client = hirebase.Client(api_key="YOUR_API_KEY")

filters = {
    "job_titles": ["sustainability", "ESG", "climate", "renewable", "\"clean energy\""],
    "geo_locations": [{"country": "United States"}],
    "date_posted_from": "2023-01-01",
}

# 1. Discover (free)
res = client.jobs.historical_search(filters, sample_size=25)
print(res["total_count"], "matches,", res["export_quote"]["price_usd"], "USD to export all")
for row in res["by_year_posted"]:
    print(row["year"], row["count"])

# 2. Export (paid per record)
order = client.jobs.historical_export(filters, format="csv")
print("Pay here:", order["checkout_url"])

# 3. After payment
success, result = client.tasks.poll(order["task_id"], timeout=1800)
print(result["download_url"] if success else result)
```

<Note>
  Looking only for **which** jobs expired since a date so you can prune your own copy? That is the free, slug-only [Expired Jobs feed](/docs/api-reference/jobs/expired-jobs), which is unchanged.
</Note>