Skip to main content

​
v2.5.5 — October 2026

  • Hiring Manager API: failure reasons. A failed contacts task now carries error_code (no_contacts_found, job_expired, job_not_found, temporary, internal) and retryable, so you can tell “submit again” from “move on” without reading the message. See Why a task failed.
  • Expired postings work. A posting that expired in the last 30 days is researched like a live one; an older one returns contacts if it was researched before, else fails with job_expired. An id that matches no posting is rejected with 404 at submit instead of creating a task that fails later.
  • Batch submit. POST /v2/jobs/contacts/batch queues up to 100 postings in one request, with a per-id error for any it can’t queue. Billing is unchanged: per posting, when it finishes.
  • Only the people you want. Every contact now has a function (legal, hr, recruiting, executive or other, from their title). Pass functions to return only those, and exclude with up to 10,000 LinkedIn URLs and emails you already have. Excluded people never cost a reveal, and a search that leaves no one after your filter and list is not charged (error_code: no_matching_contacts). Works on single and batch submit.
  • Hiring managers, labelled and first. Every contact now has a relationship: hiring_manager (the person the role reports to), function_leader, recruiter, hr, executive or other, and contacts come in that order. Pass relationships (for example ["hiring_manager"]) to return only those; like functions, a search the filter leaves empty is not charged. Works on single and batch submit. See Hiring Manager Contacts.
  • Polling has its own rate limit. Get Task Status and the newly documented List Tasks allow 600 requests per minute per key, separate from the 100 per minute every other endpoint shares.

​
v2.5.4 — October 2026

  • Historical exports include the original description. Historical Export records now include description_raw, the complete original description from the source ATS, alongside the summarised description wherever the archive still retains it.
  • Promo codes at export checkout. The Stripe Checkout for historical exports and one-off live exports accepts promotion codes. A 100% code provisions the export with no charge.
  • Salary Benchmark: deeper samples, sub-industry, and source postings. By default the sample now includes jobs that closed inside the window as well as open ones, which gives deeper samples and a month-by-month trend; set include_expired: false to use open jobs only. New sub_industry filter. result.listings returns up to 25 source postings spread across the distribution, and result.listings_total gives the full sample size. A proposed salary_range keeps its currency and period, and a benchmark whose task fails is refunded. See Salary Benchmark.
  • Neural Search warm-up. While the Neural Search model is starting up after an idle spell, POST /v2/jobs/neural-search answers 429 with code: neural_search_warming_up and a Retry-After header (30 seconds). Retry after the delay. The warm-up response is not billed.
  • location_group now filters. Each group covers a 25-mile radius around each of its cities on job search, exports, Neural Search lexical filters and Historical Jobs. An unknown group name returns 422 with the list of valid groups.
  • On hard-capped plans, a job export checks search.limit against your remaining allowance before it starts, the same way searches do. An export that won’t fit returns 429 with X-Billing-Code: limit_exceeded.

​
🐍 Python SDK 0.2.3

  • hirebase 0.2.3 waits and retries automatically while Neural Search warms up, for up to warmup_wait seconds (default 300, 0 disables). If the model still isn’t ready, it raises ModelWarmingUpError, a RateLimitError. See the SDK page.

​
🌐 hirebase.org

  • The Job Market Insights pages have new charts and maps. Salaries show in each place’s own currency next to USD, and rankings across places use annual USD.

​
v2.5.3 — October 2026

  • **Pro jobs overage is now $5.00 per 1,000** (was $1.00). Pro still includes 10,000 jobs a month for API keys. For higher API volume, the API plans (Starter, Growth, Scale) price jobs lower; see What each plan includes.

​
v2.5.2 — September 2026

  • Hiring Manager API usage is charged as it builds up. Besides the monthly invoice, the add-on now charges as soon as unbilled usage reaches a threshold, whichever comes first. The threshold starts at $10 and rises to $50, then $100, after each successful charge. Prices are unchanged. See Hiring Manager Contacts.
  • Resubmitting a job_id within 24 hours of a charged contacts search is no longer charged again.
  • If a Hiring Manager charge fails, new contacts and reveal requests return 402 with "code": "payment_failed" until the payment goes through; queued tasks keep running. See Payment Errors.

​
v2.5.1 — September 2026

  • Vector search is no longer a public endpoint. POST /v2/jobs/vsearch has been removed from the docs. Neural Search covers every use it had — free-text similarity via vector.query, “more like this job” via vector.job_ids, resume matching via vector.artifact_id — and adds lexical filters on top. Existing integrations should migrate; see Choosing the Right API.
  • Unknown request parameters on company search, job search, estimate, insights, export, salary benchmark, and expired export now return 422 instead of being silently ignored.
  • The expired-jobs feed and export now cover the last 14 days. A since older than midnight UTC 14 days ago returns 400. Both are for hourly or daily syncs of a live copy; for past postings use Historical Jobs.
  • The expired-jobs feed returns 400 instead of timing out when you jump straight to a page more than 200,000 records deep. Walk pages in order, or use Export Expired Jobs.

​
🐍 Python SDK 0.2.2

  • hirebase 0.2.2 is on PyPI with jobs.historical_search / jobs.historical_export (Historical Jobs), jobs.contacts / jobs.reveal_contact (Hiring Manager Contacts), and return_meta=True for reading usage headers per call. See the SDK page. (0.2.1 sent an include_expired field on salary benchmarks that the API does not accept yet; use 0.2.2.)

​
v2.5.0 — September 2026

Metering consolidation, quota hardening, and a salary benchmark endpoint.

​
📊 Metering & plans

  • One jobs meter. Everything that returns jobs — lexical search, vector search, neural search, company jobs, exports, expired-job exports — now bills m_jobs_api_calls. The separate vector, semantic, and export meters are retired; company routes bill m_company_api_calls. See What each endpoint costs.
  • GET /v2/jobs/expired-jobs now costs 0 (it returns identifiers only). POST /v2/jobs/expired-jobs/export is also free: expired data is not billed, only live job data is.
  • POST /v2/jobs/estimate is documented: free, and still available once you hit a cap.
  • Export on every plan, including Free (bounded by the 500-job allowance).
  • Pro API keys get 10,000 jobs (metered overage) and 2,000 companies (hard cap) per month.
  • Plan allowances and overage rates are now listed in one place: What each plan includes.

​
🛡️ Caps

  • Hard caps are enforced before a request runs, using its worst-case cost (the requested limit). A request that cannot fit in the remaining allowance is refused with 429 / X-Billing-Code: limit_exceeded and a message stating how many units remain; parallel requests can no longer overshoot a cap.
  • Cap and feature errors now say where to upgrade (/v2/billing/portal).

​
🔧 Fixes

  • Hirebase-Usage-* headers are back on every metered response for paid plans (they were missing for accounts whose billing period was stored in an older format), and Period-Start/Period-End now agree with Usage Summary.
  • Usage counters no longer reset during the nightly billing sync.

​
💰 Salary Benchmark

  • New endpoint: POST /v2/jobs/salary-benchmark — market percentiles, sample size, confidence grade, and the percentile of a proposed range. One m_salary_benchmarks unit per request; 3/month on Free, 25/month on API plans, 500/month on Pro.

​
🐍 Python SDK 0.2.x

  • New methods: jobs.estimate, jobs.expired, jobs.export_expired, jobs.vsearch, jobs.salary_benchmark, companies.jobs, usage.get, resumes.upload / get / parse / upload_and_parse, tasks.get.
  • return_meta=True on any metered method returns the Hirebase-Usage-* headers with the result; QuotaExceededError distinguishes plan-cap 429s from rate limits; RateLimitError.retry_after.

​
v2.4.0 — August 2026

Billing, metering, and export release: usage visibility, per-plan quotas, and a new expired-jobs export pipeline.

​
🔓 Authentication (breaking)

  • All data endpoints now require an API key on every request, including page 1 of search results. Anonymous requests return 401. (Supersedes the v2.3.0 free-first-page behavior; only the reference-data endpoints remain keyless.) See Authentication.

​
📤 Exports

  • New endpoint: POST /v2/jobs/expired-jobs/export — async JSONL export of the expired-jobs feed since a date. Flat cost of 1 unit per export; the recommended path for historical backfills (no page-depth limits).
  • notify: true on export requests sends a completion email with the download link.
  • Task objects now include notify, and type may be export_expired_jobs.

​
📊 Billing & Usage

  • New endpoints: GET /v2/billing/usage/summary (current-period per-meter usage, plan, and allowances) and GET /v2/billing/usage/daily (daily timeseries, up to 90 days).
  • Hirebase-Usage-* response headers on metered API responses — meter, included/used/remaining, and overage for the request you just made, CORS-exposed for browser clients. See Usage Headers & Metering.
  • Per-endpoint metering across six meters (jobs, vector, semantic, company, exports, insights). Search calls bill per result returned; job exports bill min(limit, matches) at task creation.
  • At a plan cap: 429 with X-Billing-Code: limit_exceeded on hard-capped plans; metered-overage plans continue past included usage. Feature not in plan: 403 with X-Billing-Code: feature_missing.

​
⚙️ Limits & Behavior

  • Rate limits: 100 requests / 60 s per API key (25/60 s unauthenticated); 429 responses include Retry-After and X-RateLimit-* headers.
  • Search limit maximum raised to 100 results per page.
  • Salary filter fixes: results respect the requested salary range.
  • Guest (unauthenticated) export checkout is discontinued; POST /v2/jobs/public/export now requires authentication.

​
v2.3.0 — April 2026

Quality-of-life release focused on richer job metadata, better filter ergonomics, and a free-tier developer experience.

​
🔓 Authentication

  • Free first page. All search endpoints now return the first page of results without an API key. Page 2+ (and always-authed endpoints like Expired Jobs, Export Jobs, Resume Embed, Task Status) still require a key in the x-api-key header.

​
🧠 Richer Job Metadata

  • New scoring fields on job objects (0–10 scale): coolness_score, flexibility_score, compensation_value_score, benefits_score, impact_autonomy_score, prestige_score, growth_score.
  • meta_completeness boolean flag on job objects (not a score).
  • New parsed fields: experience_level, skills, technologies, benefits, education_level, team, language, contact_email, contact_phone, recruiter_agency.
  • return_raw_description: "true" now returns a description_raw field with the full original HTML from the ATS source.

​
🔍 Search API Enhancements

  • company_count added to the response alongside total_count / total_pages for unique-company rollups.
  • New filter parameters: location_group, company_types, date_posted, month, currency, include_expired, include_no_salary, include_yoe, hide_seen_jobs, filter_incomplete_jobs, job_category.
  • sort_by now accepts company and yoe in addition to relevance / date_posted / salary.
  • Request-side experience filter standardized to Entry, Junior, Mid, Senior, Executive. Response experience_level values remain longer-form (Entry-Level, Mid-Level, Principal / Staff / Lead, etc.).
  • job_types replaces the previous job_type parameter (plural, array-valued).

​
🧩 Reference Data Endpoints

  • GET /v2/jobs/data/categories — canonical list of job category tags.
  • GET /v2/jobs/data/industries — canonical list of industries.
  • GET /v2/jobs/data/subindustries — canonical list of subindustries.

​
📚 Docs

  • Migrated configuration from mint.json to docs.json.
  • Expanded response schemas and working cURL examples across endpoint pages. (OpenAPI spec at /docs/api-reference/openapi.json is not yet populated.)
  • Added an Expired Jobs API reference page.

​
v2.2.0

Location and keyword matching overhaul, plus new filter parameters to improve job filtering.

​
🔧 API & Developer Experience

  • Updated Endpoints:
  • /v2/jobs/neural-search for semantic search
  • /v2/jobs/search for text search
  • /v2/jobs/export for CSV/JSON export
  • v2/hirebase/companies/search for Company Search

​
Job Exports

  • Job Exports have been made into a service which you can now track via your settings.
  • Export data will last 30 days before deletion, see User Settings to view your exports.
  • Job Exports is now available via API.

​
🔍 Job Search Enhancements

  • Location Filtering: Geographic, text, and area-based matching via geofilter_params.
  • Hide Recruiter Agencies: Removes recruiting-agency posts from the search and export feeds via hide_recruiting_agencies.
  • Company filtering: Filter for company-specific data using company_keywords such as goods and services.

​
📚 Docs & Guides

  • Multi-language code examples.
  • Guides for search, subscriptions, and integration.
Note: Please report any issues directly to spencer@hirebase.org. We release bug-fix updates based on severity. For full documentation and support, visit the Hirebase API docs.