Skip to main content

​
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.
  • client.last_usage exposes the usage headers after every call; 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.
  • New task pages: List Tasks and Cancel Task are documented; 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.