{"openapi":"3.1.0","info":{"title":"Headcount Labs API","version":"0.1.0","description":"Search and sync job postings collected from employers' own job sources, with company records.\n\nAuthentication: send your API key as a bearer token, Authorization: Bearer jc_live_<id>.<secret> (keys issued before October 2026 start with ar_live_ and still work). Create keys in your account. A missing or wrong key returns 401 invalid_api_key.\n\nPaging: list endpoints return next_cursor; pass it back as cursor for the next page. Every page of one listing reads the same catalog snapshot (snapshot_watermark), so results don't shift under you. A cursor from an older snapshot or with different filters returns 400; start again from the first page.\n\nKeeping in sync: pull GET /v1/jobs/changes with since for the first call, then keep passing resume_cursor as after to receive created, updated and expired jobs in order.\n\nLimits: every API key includes up to 1,000,000 jobs a day free (10,000 requests of up to 100 jobs each, shared by every request type). Getting one job never counts. Past the free allowance you pay per request: $0.02 per 1,000 requests for filtered lists and counts and $0.20 per 1,000 for keyword searches, with automatic volume discounts each calendar month (25% off from 1 million to 10 million paid requests, 50% off over 10 million). Add prepaid usage or turn on pay as you go to keep going; see https://headcountlabs.com/pricing/. Requests are also limited per minute. Going over returns 429 (rate_limited or data_limit_exceeded) with a Retry-After header in seconds. Counts and usage reports return no records.\n\nErrors always look like {\"error\": {\"code\", \"message\", \"request_id\"}}. Quote request_id when you contact support. 503 catalog_unavailable means the jobs catalog is being published; retry shortly. 504 query_timeout means a search ran longer than 10 seconds and was stopped; it uses no records. Narrow the filters and try again."},"servers":[{"url":"/"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/companies":{"get":{"operationId":"listCompanies","summary":"Browse companies","description":"Lists companies from one immutable registry release.","x-applyrelay-availability":"pending_registry_release","parameters":[{"name":"name","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Case-insensitive canonical-name substring."},{"$ref":"#/components/parameters/CompanyLimit"},{"$ref":"#/components/parameters/CompanyCursor"}],"responses":{"200":{"description":"A page of public company records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPage"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/companies/search":{"post":{"operationId":"searchCompanies","summary":"Search companies","description":"Combines verified name, country, and status filters with AND. Search uses the same UUID company records and release-pinned cursor as company browse.","x-applyrelay-availability":"pending_registry_release","requestBody":{"required":true,"description":"JSON object of at most 16,384 bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchRequest"}}}},"responses":{"200":{"description":"A page of matching public company records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPage"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/companies/{companyId}":{"get":{"operationId":"getCompany","summary":"Get a company by UUID","x-applyrelay-availability":"pending_registry_release","parameters":[{"$ref":"#/components/parameters/CompanyId"}],"responses":{"200":{"description":"A public company record.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Company"}}}}}},"308":{"description":"A merged company ID redirects to its current UUID.","headers":{"Location":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/companies/{companyId}/jobs":{"get":{"operationId":"listCompanyJobs","summary":"List a company's jobs","description":"Lists the company's public jobs from the latest published jobs catalog, with the same filters, order and cursor rules as GET /v1/jobs. Resolves the company UUID and redirects merged IDs. Requires an active company registry release and a published jobs catalog, and responds 503 while either is missing.","x-applyrelay-availability":"pending_jobs_catalog","parameters":[{"$ref":"#/components/parameters/CompanyId"},{"name":"fields","in":"query","description":"Comma list of the job properties to return; repeat the parameter or separate names with commas. Allowed names are job_id, currentness, stale, company_id, employer_name, title, description, work_arrangement, locations, job_first_seen_at, curated_at, job_updated_at, postings and company. job_id is always returned. Without fields the whole job is returned. An unknown name returns 400. It changes only the shape of each job, never which jobs match.","schema":{"type":"string","example":"title,employer_name,locations"}}],"responses":{"308":{"description":"A merged company ID redirects to its current UUID.","headers":{"Location":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/QueryTimeout"}}}},"/v1/jobs":{"get":{"operationId":"listJobs","summary":"List public jobs","description":"Returns included public jobs from the latest published jobs catalog. A search with q, title or description is ranked by relevance, with title matches weighted ten times description matches; any other list, or sort=updated, is newest job_updated_at first. Ties break by job_id, descending. Without a currentness or active filter only current jobs are returned. Every page of one listing reads the same catalog snapshot: next_cursor is bound to that snapshot, the filters and the limit, and a cursor from an older snapshot or a different query returns 400. Responds 503 catalog_unavailable while no jobs catalog has been published.","x-applyrelay-availability":"pending_jobs_catalog","parameters":[{"name":"company","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Employer name contains this text. Case-insensitive. 1-200 characters. A term of 1-2 characters matches the whole employer name or its first word instead (`hp` finds \"HP Inc.\" but not \"Shop HP Repairs\")."},{"name":"company_id","in":"query","schema":{"$ref":"#/components/schemas/CompanyId"},"description":"Only jobs of this company, by its Headcount Labs company ID (lowercase UUID)."},{"name":"title","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Job title contains these words as one phrase, in this order (full-text match). \"senior software engineer\" does not match \"Software Engineer, Senior\" or \"Senior Staff Software Engineer\"; use title_advanced, such as senior AND \"software engineer\", to match the words in any order. 1-200 characters."},{"name":"title_advanced","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"example":"nurse AND NOT manager","description":"Boolean title search: the words may appear in any order. Supports AND, OR and NOT keywords, &, | and !, parentheses, prefix terms such as engineer:*, and quoted phrases such as \"product manager\". Prefer it over title when job titles vary in word order, for example senior AND (\"software engineer\" OR \"software developer\"). A positive search term is required."},{"name":"description_advanced","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"example":"\"product manager\"","description":"Boolean description search. Supports AND, OR and NOT keywords, &, | and !, parentheses, prefix terms such as engineer:*, and quoted phrases such as \"product manager\". A positive search term is required."},{"name":"q","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Keyword search: the phrase appears in the title or description. Results are ranked by relevance unless sort=updated. 1-200 characters."},{"name":"location","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any job location contains this text (city, region or country as written). Case-insensitive. 1-200 characters."},{"name":"state","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Two-letter subdivision code. On its own it means a U.S. state (state=CA is California only); combine with country for another country's subdivision (country=CA&state=BC is British Columbia)."},{"name":"country","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}(,[A-Za-z]{2}){0,9}$","example":"US,CA"},"description":"Two-letter ISO country code, for example US or CA. Case-insensitive. Send up to 10 codes separated by commas to match jobs in any of them."},{"name":"msa","in":"query","schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"5-digit CBSA code of a metropolitan or micropolitan statistical area, for example 12420 for Austin-Round Rock-San Marcos, TX. Matches any job location whose msa.cbsa_code equals it."},{"name":"work_arrangement","in":"query","schema":{"type":"string","enum":["remote","hybrid","in_person"]},"description":"One of remote, hybrid or in_person, as the source states it. Jobs whose source doesn't say are not matched."},{"name":"remote_type","in":"query","description":"Alias for work_arrangement; do not send both.","schema":{"type":"string","enum":["remote","hybrid","in_person"]}},{"name":"employment_type","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Employment type as published, for example full_time or part_time. Exact match, case-insensitive. Send up to 10 values separated by commas to match jobs with any of them."},{"name":"source","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"The source vendor, such as greenhouse or smartrecruiters. Board IDs are not exposed."},{"name":"currentness","in":"query","description":"Comma list of current, uncertain and not_current.","schema":{"type":"string","default":"current","example":"current,uncertain"}},{"name":"active","in":"query","description":"true maps to currentness=current and false to currentness=not_current; do not send with currentness.","schema":{"type":"boolean"}},{"name":"posted_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Posted on or after this time, by the date the source published. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21). A plain date means the start of that day in UTC."},{"name":"posted_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Posted on or before this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21). A plain date means the end of that day in UTC."},{"name":"published_since","in":"query","description":"Compatibility alias for posted_since; do not send both.","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"first_seen_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"First collected by Headcount Labs on or after this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},{"name":"updated_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Job record last changed on or after this time; use it for incremental pulls. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},{"name":"curated_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Entered the final dataset on or after this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},{"name":"job_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"One job by its job ID (a lowercase UUID)."},{"name":"description","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Words that must appear together in the job description. Use description_advanced for a Boolean expression."},{"name":"city","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"City name. Matches any job location whose city contains this text, case-insensitive. Combine with state and country to narrow it."},{"name":"exclude_source","in":"query","schema":{"type":"string","maxLength":200,"example":"indeed,linkedin"},"description":"Comma list of up to 10 source vendors or source types to leave out. A job still matches when another of its postings comes from a source not on the list."},{"name":"source_type","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"The kind of job source, as in postings[].source_data.source_type. Exact match, case-insensitive."},{"name":"source_class","in":"query","schema":{"type":"string","enum":["ats","employer-site","government-exchange","aggregator","staffing-network","dataset","purchased","third-party-api","unknown"]},"description":"The class of job source a posting came from, for example ats for an applicant tracking system board or employer-site for a company's own careers page."},{"name":"posting_id","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"The job that holds this posting, by Headcount Labs' posting ID."},{"name":"source_posting_id","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Jobs with a posting that has this source posting ID (the job source's own ID for the listing)."},{"name":"posting_status","in":"query","schema":{"type":"string","enum":["listed","no_longer_listed"]},"description":"Jobs with a posting in this state. listed means the source still shows it; no_longer_listed means a completed read no longer found it."},{"name":"stale","in":"query","schema":{"type":"boolean"},"description":"true for jobs flagged stale, false for the rest. The flag is a label published with the job. Stale jobs stay in results, and stale=false leaves them out."},{"name":"company_linked","in":"query","schema":{"type":"boolean"},"description":"true for jobs linked to a company record (company_id is set); false for jobs with no linked company."},{"name":"has_description","in":"query","schema":{"type":"boolean"},"description":"true for jobs with a known description; false for jobs without one."},{"name":"has_location","in":"query","schema":{"type":"boolean"},"description":"true for jobs with at least one known location; false for jobs with none."},{"name":"has_pay","in":"query","schema":{"type":"boolean"},"description":"true for jobs with a posting that publishes pay; false for jobs with a posting that does not."},{"name":"has_posting_url","in":"query","schema":{"type":"boolean"},"description":"true for jobs with a posting that has a known listing URL."},{"name":"has_application_url","in":"query","schema":{"type":"boolean"},"description":"true for jobs with a posting that has a known application URL."},{"name":"pay_currency","in":"query","schema":{"type":"string","example":"USD"},"description":"ISO 4217 currency code. Jobs with a posting whose published pay is in this currency."},{"name":"pay_min","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000000},"description":"Lowest yearly pay. Matches postings whose pay floor is at least this amount. Pay is compared per year (hourly x 2,080, monthly x 12); pay with an unknown interval never matches. Amounts are not converted between currencies, so pair it with pay_currency. Up to two decimal places."},{"name":"pay_max","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000000},"description":"Highest yearly pay. Matches postings whose pay ceiling is at most this amount, compared per year the same way as pay_min. Must not be below pay_min."},{"name":"first_seen_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"First collected by Headcount Labs on or before this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"updated_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Last changed on or before this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"curated_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Entered the final dataset on or before this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"last_fetch_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Jobs with a posting whose job source was last read completely on or after this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"last_fetch_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Jobs with a posting whose job source was last read completely on or before this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"application_check","in":"query","schema":{"type":"string","enum":["available","closed","broken","inconclusive"]},"description":"Jobs with a posting whose latest application check had this result. available means an application could still be started."},{"name":"application_check_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Jobs with a posting whose latest application check ran on or after this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"include","in":"query","description":"Comma list containing company and/or source_data. company adds the linked public company record; source_data adds each posting's source data.","schema":{"type":"string","example":"company,source_data"}},{"name":"fields","in":"query","description":"Comma list of the job properties to return; repeat the parameter or separate names with commas. Allowed names are job_id, currentness, stale, company_id, employer_name, title, description, work_arrangement, locations, job_first_seen_at, curated_at, job_updated_at, postings and company. job_id is always returned. Without fields the whole job is returned. An unknown name returns 400. It changes only the shape of each job, never which jobs match.","schema":{"type":"string","example":"title,employer_name,locations"}},{"name":"description_format","in":"query","description":"text returns descriptions as plain text. html returns 503 because source HTML descriptions are not published yet.","schema":{"type":"string","enum":["text","html"],"default":"text"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":50},"description":"Page size, 1-250, or 1-1,000 when fields is exactly job_id. Defaults to 50."},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1,"maxLength":2048},"description":"The next_cursor from the previous page. It is tied to the same filters, page size, sort and catalog snapshot; start again from the first page if you get a 400 for a stale cursor."},{"name":"sort","in":"query","schema":{"type":"string","enum":["relevance","updated"]},"description":"relevance ranks by how well q, title and description match, and is the default when one of them is set; it returns 400 without one. updated lists the most recently updated jobs first, and is the default otherwise."}],"responses":{"200":{"description":"A page of public job records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/QueryTimeout"}}}},"/v1/jobs/search":{"post":{"operationId":"searchPublicJobs","summary":"Search public jobs with a JSON body","description":"Takes the same filters, paging and representation options as GET /v1/jobs as one JSON object (Content-Type application/json, at most 16,384 bytes). Unknown keys are rejected. Booleans and numbers must be JSON booleans and numbers. currentness and include must be arrays; country, employment_type and fields may be strings or arrays. Send next_cursor back as cursor in the body for the next page. The response, request charge, limits and errors match GET /v1/jobs. Page size is 1-250, or 1-1000 when fields is exactly job_id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"company":{"type":"string","minLength":1,"maxLength":200,"description":"Employer name contains this text. Case-insensitive. 1-200 characters. A term of 1-2 characters matches the whole employer name or its first word instead (`hp` finds \"HP Inc.\" but not \"Shop HP Repairs\")."},"company_id":{"$ref":"#/components/schemas/CompanyId","description":"Only jobs of this company, by its Headcount Labs company ID (lowercase UUID)."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Job title contains these words as one phrase, in this order (full-text match). \"senior software engineer\" does not match \"Software Engineer, Senior\" or \"Senior Staff Software Engineer\"; use title_advanced, such as senior AND \"software engineer\", to match the words in any order. 1-200 characters."},"title_advanced":{"type":"string","minLength":1,"maxLength":200,"description":"Boolean title search: the words may appear in any order. Supports AND, OR and NOT keywords, &, | and !, parentheses, prefix terms such as engineer:*, and quoted phrases such as \"product manager\". Prefer it over title when job titles vary in word order, for example senior AND (\"software engineer\" OR \"software developer\"). A positive search term is required."},"description_advanced":{"type":"string","minLength":1,"maxLength":200,"description":"Boolean description search. Supports AND, OR and NOT keywords, &, | and !, parentheses, prefix terms such as engineer:*, and quoted phrases such as \"product manager\". A positive search term is required."},"q":{"type":"string","minLength":1,"maxLength":200,"description":"Keyword search: the phrase appears in the title or description. Results are ranked by relevance unless sort=updated. 1-200 characters."},"location":{"type":"string","minLength":1,"maxLength":200,"description":"Any job location contains this text (city, region or country as written). Case-insensitive. 1-200 characters."},"state":{"type":"string","minLength":1,"maxLength":200,"description":"Two-letter subdivision code. On its own it means a U.S. state (state=CA is California only); combine with country for another country's subdivision (country=CA&state=BC is British Columbia)."},"country":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Two-letter ISO country code, for example US or CA. Case-insensitive. Send up to 10 codes separated by commas to match jobs in any of them. In a JSON body this may be a string or an array of strings."},"msa":{"type":"string","pattern":"^[0-9]{5}$","description":"5-digit CBSA code of a metropolitan or micropolitan statistical area, for example 12420 for Austin-Round Rock-San Marcos, TX. Matches any job location whose msa.cbsa_code equals it."},"work_arrangement":{"type":"string","enum":["remote","hybrid","in_person"],"description":"One of remote, hybrid or in_person, as the source states it. Jobs whose source doesn't say are not matched."},"remote_type":{"type":"string","enum":["remote","hybrid","in_person"],"description":"Alias for work_arrangement; do not send both."},"employment_type":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Employment type as published, for example full_time or part_time. Exact match, case-insensitive. Send up to 10 values separated by commas to match jobs with any of them. In a JSON body this may be a string or an array of strings."},"source":{"type":"string","minLength":1,"maxLength":200,"description":"The source vendor, such as greenhouse or smartrecruiters. Board IDs are not exposed."},"currentness":{"type":"array","items":{"type":"string"},"description":"Comma list of current, uncertain and not_current. In a JSON body this must be an array of strings."},"active":{"type":"boolean","description":"true maps to currentness=current and false to currentness=not_current; do not send with currentness."},"posted_since":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Posted on or after this time, by the date the source published. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21). A plain date means the start of that day in UTC."},"posted_until":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Posted on or before this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21). A plain date means the end of that day in UTC."},"published_since":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Compatibility alias for posted_since; do not send both."},"first_seen_since":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"First collected by Headcount Labs on or after this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},"updated_since":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Job record last changed on or after this time; use it for incremental pulls. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},"curated_since":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Entered the final dataset on or after this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},"job_id":{"type":"string","format":"uuid","description":"One job by its job ID (a lowercase UUID)."},"description":{"type":"string","minLength":1,"maxLength":200,"description":"Words that must appear together in the job description. Use description_advanced for a Boolean expression."},"city":{"type":"string","minLength":1,"maxLength":200,"description":"City name. Matches any job location whose city contains this text, case-insensitive. Combine with state and country to narrow it."},"exclude_source":{"type":"string","maxLength":200,"example":"indeed,linkedin","description":"Comma list of up to 10 source vendors or source types to leave out. A job still matches when another of its postings comes from a source not on the list."},"source_type":{"type":"string","minLength":1,"maxLength":200,"description":"The kind of job source, as in postings[].source_data.source_type. Exact match, case-insensitive."},"source_class":{"type":"string","enum":["ats","employer-site","government-exchange","aggregator","staffing-network","dataset","purchased","third-party-api","unknown"],"description":"The class of job source a posting came from, for example ats for an applicant tracking system board or employer-site for a company's own careers page."},"posting_id":{"type":"string","minLength":1,"maxLength":200,"description":"The job that holds this posting, by Headcount Labs' posting ID."},"source_posting_id":{"type":"string","minLength":1,"maxLength":200,"description":"Jobs with a posting that has this source posting ID (the job source's own ID for the listing)."},"posting_status":{"type":"string","enum":["listed","no_longer_listed"],"description":"Jobs with a posting in this state. listed means the source still shows it; no_longer_listed means a completed read no longer found it."},"stale":{"type":"boolean","description":"true for jobs flagged stale, false for the rest. The flag is a label published with the job. Stale jobs stay in results, and stale=false leaves them out."},"company_linked":{"type":"boolean","description":"true for jobs linked to a company record (company_id is set); false for jobs with no linked company."},"has_description":{"type":"boolean","description":"true for jobs with a known description; false for jobs without one."},"has_location":{"type":"boolean","description":"true for jobs with at least one known location; false for jobs with none."},"has_pay":{"type":"boolean","description":"true for jobs with a posting that publishes pay; false for jobs with a posting that does not."},"has_posting_url":{"type":"boolean","description":"true for jobs with a posting that has a known listing URL."},"has_application_url":{"type":"boolean","description":"true for jobs with a posting that has a known application URL."},"pay_currency":{"type":"string","example":"USD","description":"ISO 4217 currency code. Jobs with a posting whose published pay is in this currency."},"pay_min":{"type":"number","minimum":0,"maximum":1000000000,"description":"Lowest yearly pay. Matches postings whose pay floor is at least this amount. Pay is compared per year (hourly x 2,080, monthly x 12); pay with an unknown interval never matches. Amounts are not converted between currencies, so pair it with pay_currency. Up to two decimal places."},"pay_max":{"type":"number","minimum":0,"maximum":1000000000,"description":"Highest yearly pay. Matches postings whose pay ceiling is at most this amount, compared per year the same way as pay_min. Must not be below pay_min."},"first_seen_until":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"First collected by Headcount Labs on or before this time. Accepts an RFC 3339 timestamp or a plain date."},"updated_until":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Last changed on or before this time. Accepts an RFC 3339 timestamp or a plain date."},"curated_until":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Entered the final dataset on or before this time. Accepts an RFC 3339 timestamp or a plain date."},"last_fetch_since":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Jobs with a posting whose job source was last read completely on or after this time. Accepts an RFC 3339 timestamp or a plain date."},"last_fetch_until":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Jobs with a posting whose job source was last read completely on or before this time. Accepts an RFC 3339 timestamp or a plain date."},"application_check":{"type":"string","enum":["available","closed","broken","inconclusive"],"description":"Jobs with a posting whose latest application check had this result. available means an application could still be started."},"application_check_since":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Jobs with a posting whose latest application check ran on or after this time. Accepts an RFC 3339 timestamp or a plain date."},"include":{"type":"array","items":{"type":"string"},"description":"Comma list containing company and/or source_data. company adds the linked public company record; source_data adds each posting's source data. In a JSON body this must be an array of strings."},"fields":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Comma list of the job properties to return; repeat the parameter or separate names with commas. Allowed names are job_id, currentness, stale, company_id, employer_name, title, description, work_arrangement, locations, job_first_seen_at, curated_at, job_updated_at, postings and company. job_id is always returned. Without fields the whole job is returned. An unknown name returns 400. It changes only the shape of each job, never which jobs match. In a JSON body this may be a string or an array of strings."},"description_format":{"type":"string","enum":["text","html"],"default":"text","description":"text returns descriptions as plain text. html returns 503 because source HTML descriptions are not published yet."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":50,"description":"Page size, 1-250, or 1-1,000 when fields is exactly job_id. Defaults to 50."},"cursor":{"type":"string","minLength":1,"maxLength":2048,"description":"The next_cursor from the previous page. It is tied to the same filters, page size, sort and catalog snapshot; start again from the first page if you get a 400 for a stale cursor."},"sort":{"type":"string","enum":["relevance","updated"],"description":"relevance ranks by how well q, title and description match, and is the default when one of them is set; it returns 400 without one. updated lists the most recently updated jobs first, and is the default otherwise."}}}}}},"responses":{"200":{"description":"A page of public job records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/QueryTimeout"}}}},"/v1/jobs/search/es_dsl":{"post":{"operationId":"searchPublicJobsEsDsl","summary":"Search public jobs with Elasticsearch-style clauses","description":"Translates the supported Elasticsearch-style query subset to the same filters as POST /v1/jobs/search. All must and filter clauses are AND-ed. should is supported only for term or match clauses on the same country or employment_type field, including when must/filter is also present. Range gt is treated as inclusive gte, and lt as inclusive lte. The response, cursor, request charge, limits, and errors match POST /v1/jobs/search. Page size is 1-250, or 1-1000 when fields is exactly job_id.","requestBody":{"required":true,"description":"JSON object of at most 16,384 bytes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"object","description":"One supported clause: match_all, bool, term, terms, match, match_phrase, range, exists, query_string, or simple_query_string. Unsupported clauses and fields return 400 invalid_request. See the operation description and Headcount Labs API documentation for the accepted field list."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":50,"description":"Page size 1-250. Values 251-1000 are accepted only when fields is exactly job_id."},"cursor":{"type":"string","minLength":1,"maxLength":2048},"sort":{"type":"string","enum":["relevance","updated"]},"fields":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"include":{"type":"array","items":{"type":"string","enum":["company","source_data"]}},"description_format":{"type":"string","enum":["text","html"],"default":"text"}}}}}},"responses":{"200":{"description":"A page of public job records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/QueryTimeout"}}}},"/v1/jobs/exports":{"post":{"summary":"Create a bulk jobs export","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Filter fields use the same names and validation as POST /v1/jobs/search. Supports search filters, fields, include, description_format, and sort; limit and cursor are forbidden.","additionalProperties":true,"properties":{"q":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}},"include":{"type":"array","items":{"type":"string","enum":["company","source_data"]}},"description_format":{"type":"string","enum":["text","html"],"default":"text"},"sort":{"type":"string","enum":["relevance","updated"]},"max_records":{"type":"integer","minimum":1,"maximum":100000,"default":100000}},"not":{"anyOf":[{"required":["limit"]},{"required":["cursor"]}]}}}}},"responses":{"202":{"description":"Export accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobsExport"}}}},"400":{"description":"Invalid export request"},"401":{"description":"Invalid API key"},"409":{"description":"The account already has a queued or running export"},"429":{"description":"Request allowance is insufficient"},"503":{"description":"Export service is unavailable"}}},"get":{"summary":"List recent jobs exports","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Exports for the authenticated account, newest first, limited to 20","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JobsExport"}}}}}}},"401":{"description":"Invalid API key"},"503":{"description":"Export service is unavailable"}}}},"/v1/jobs/exports/{exportId}":{"get":{"summary":"Get a jobs export","security":[{"bearerAuth":[]}],"parameters":[{"name":"exportId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Export status and file metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobsExport"}}}},"401":{"description":"Invalid API key"},"404":{"description":"Export does not exist or belongs to another account"},"503":{"description":"Export service is unavailable"}}}},"/v1/jobs/exports/{exportId}/files/{n}":{"get":{"summary":"Download a gzip JSON Lines export file","security":[{"bearerAuth":[]}],"parameters":[{"name":"exportId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"n","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Gzip-compressed JSON Lines file","headers":{"Content-Disposition":{"schema":{"type":"string"},"example":"attachment; filename=\"jobs-00000000-0000-4000-8000-000000000000-1.jsonl.gz\""}},"content":{"application/gzip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Invalid API key"},"404":{"description":"File is unknown, not ready, expired, or belongs to another account"},"503":{"description":"Export service is unavailable"}}}},"/v1/jobs/changes":{"get":{"operationId":"listJobChanges","summary":"List public job changes","description":"Lists created, updated and expired job events from the latest published jobs catalog, in event order. Send exactly one of since or after: start with since, then pass resume_cursor as after. A cursor from an older catalog snapshot returns 400. Responds 503 catalog_unavailable while no jobs catalog has been published, and 503 service_unavailable when the catalog changes during the request (retry).","x-applyrelay-availability":"pending_jobs_catalog","parameters":[{"name":"after","in":"query","schema":{"type":"string","minLength":1,"maxLength":2048},"description":"The resume_cursor from your previous changes call. Send exactly one of after or since."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Start of the change window: changes strictly after this RFC 3339 timestamp. Use it for the first call, then continue with after."},{"name":"types","in":"query","schema":{"type":"string","default":"created,updated,expired"},"description":"Comma list of created, updated and expired. Defaults to all three."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100},"description":"Events per page, 1-1,000. Defaults to 100."},{"name":"company_id","in":"query","schema":{"$ref":"#/components/schemas/CompanyId"},"description":"Only changes for this company's jobs (lowercase UUID)."},{"name":"include","in":"query","schema":{"type":"string","enum":["source_data"]},"description":"source_data adds allowlisted source metadata to each job in the events. The source payload and internal extraction details are not published."}],"responses":{"200":{"description":"A page of job changes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobsChangesResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/QueryTimeout"}}}},"/v1/jobs/count":{"get":{"operationId":"countJobs","summary":"Count public jobs","description":"Counts jobs matching the same filters as GET /v1/jobs in the latest published jobs catalog, with that catalog's snapshot watermark. Responds 503 catalog_unavailable while no jobs catalog has been published.","x-applyrelay-availability":"pending_jobs_catalog","parameters":[{"name":"company","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Employer name contains this text. Case-insensitive. 1-200 characters. A term of 1-2 characters matches the whole employer name or its first word instead (`hp` finds \"HP Inc.\" but not \"Shop HP Repairs\")."},{"name":"company_id","in":"query","schema":{"$ref":"#/components/schemas/CompanyId"},"description":"Only jobs of this company, by its Headcount Labs company ID (lowercase UUID)."},{"name":"title","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Job title contains these words as one phrase, in this order (full-text match). \"senior software engineer\" does not match \"Software Engineer, Senior\" or \"Senior Staff Software Engineer\"; use title_advanced, such as senior AND \"software engineer\", to match the words in any order. 1-200 characters."},{"name":"title_advanced","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"example":"nurse AND NOT manager","description":"Boolean title search: the words may appear in any order. Supports AND, OR and NOT keywords, &, | and !, parentheses, prefix terms such as engineer:*, and quoted phrases such as \"product manager\". Prefer it over title when job titles vary in word order, for example senior AND (\"software engineer\" OR \"software developer\"). A positive search term is required."},{"name":"description_advanced","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"example":"\"product manager\"","description":"Boolean description search. Supports AND, OR and NOT keywords, &, | and !, parentheses, prefix terms such as engineer:*, and quoted phrases such as \"product manager\". A positive search term is required."},{"name":"q","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Keyword search: the phrase appears in the title or description. 1-200 characters."},{"name":"location","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any job location contains this text (city, region or country as written). Case-insensitive. 1-200 characters."},{"name":"state","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Two-letter subdivision code. On its own it means a U.S. state (state=CA is California only); combine with country for another country's subdivision (country=CA&state=BC is British Columbia)."},{"name":"country","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}(,[A-Za-z]{2}){0,9}$","example":"US,CA"},"description":"Two-letter ISO country code, for example US or CA. Case-insensitive. Send up to 10 codes separated by commas to match jobs in any of them."},{"name":"msa","in":"query","schema":{"type":"string","pattern":"^[0-9]{5}$"},"description":"5-digit CBSA code of a metropolitan or micropolitan statistical area, for example 12420 for Austin-Round Rock-San Marcos, TX. Matches any job location whose msa.cbsa_code equals it."},{"name":"work_arrangement","in":"query","schema":{"type":"string","enum":["remote","hybrid","in_person"]},"description":"One of remote, hybrid or in_person, as the source states it. Jobs whose source doesn't say are not matched."},{"name":"remote_type","in":"query","description":"Alias for work_arrangement; do not send both.","schema":{"type":"string","enum":["remote","hybrid","in_person"]}},{"name":"employment_type","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Employment type as published, for example full_time or part_time. Exact match, case-insensitive. Send up to 10 values separated by commas to match jobs with any of them."},{"name":"source","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"The source vendor, such as greenhouse or smartrecruiters. Board IDs are not exposed."},{"name":"currentness","in":"query","schema":{"type":"string","default":"current"},"description":"Comma list of current, uncertain and not_current (combined with OR). Defaults to current. A job is current when a completed read of its job source listed it within the last 31 days and no check has found it closed."},{"name":"active","in":"query","description":"true maps to currentness=current; do not send with currentness.","schema":{"type":"boolean"}},{"name":"posted_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Posted on or after this time, by the date the source published. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21). A plain date means the start of that day in UTC."},{"name":"posted_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Posted on or before this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21). A plain date means the end of that day in UTC."},{"name":"published_since","in":"query","description":"Compatibility alias for posted_since; do not send both.","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]}},{"name":"first_seen_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"First collected by Headcount Labs on or after this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},{"name":"updated_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Job record last changed on or after this time; use it for incremental pulls. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},{"name":"curated_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Entered the final dataset on or after this time. Accepts an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21)."},{"name":"job_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"One job by its job ID (a lowercase UUID)."},{"name":"description","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Words that must appear together in the job description. Use description_advanced for a Boolean expression."},{"name":"city","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"City name. Matches any job location whose city contains this text, case-insensitive. Combine with state and country to narrow it."},{"name":"exclude_source","in":"query","schema":{"type":"string","maxLength":200,"example":"indeed,linkedin"},"description":"Comma list of up to 10 source vendors or source types to leave out. A job still matches when another of its postings comes from a source not on the list."},{"name":"source_type","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"The kind of job source, as in postings[].source_data.source_type. Exact match, case-insensitive."},{"name":"source_class","in":"query","schema":{"type":"string","enum":["ats","employer-site","government-exchange","aggregator","staffing-network","dataset","purchased","third-party-api","unknown"]},"description":"The class of job source a posting came from, for example ats for an applicant tracking system board or employer-site for a company's own careers page."},{"name":"posting_id","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"The job that holds this posting, by Headcount Labs' posting ID."},{"name":"source_posting_id","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Jobs with a posting that has this source posting ID (the job source's own ID for the listing)."},{"name":"posting_status","in":"query","schema":{"type":"string","enum":["listed","no_longer_listed"]},"description":"Jobs with a posting in this state. listed means the source still shows it; no_longer_listed means a completed read no longer found it."},{"name":"stale","in":"query","schema":{"type":"boolean"},"description":"true for jobs flagged stale, false for the rest. The flag is a label published with the job. Stale jobs stay in results, and stale=false leaves them out."},{"name":"company_linked","in":"query","schema":{"type":"boolean"},"description":"true for jobs linked to a company record (company_id is set); false for jobs with no linked company."},{"name":"has_description","in":"query","schema":{"type":"boolean"},"description":"true for jobs with a known description; false for jobs without one."},{"name":"has_location","in":"query","schema":{"type":"boolean"},"description":"true for jobs with at least one known location; false for jobs with none."},{"name":"has_pay","in":"query","schema":{"type":"boolean"},"description":"true for jobs with a posting that publishes pay; false for jobs with a posting that does not."},{"name":"has_posting_url","in":"query","schema":{"type":"boolean"},"description":"true for jobs with a posting that has a known listing URL."},{"name":"has_application_url","in":"query","schema":{"type":"boolean"},"description":"true for jobs with a posting that has a known application URL."},{"name":"pay_currency","in":"query","schema":{"type":"string","example":"USD"},"description":"ISO 4217 currency code. Jobs with a posting whose published pay is in this currency."},{"name":"pay_min","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000000},"description":"Lowest yearly pay. Matches postings whose pay floor is at least this amount. Pay is compared per year (hourly x 2,080, monthly x 12); pay with an unknown interval never matches. Amounts are not converted between currencies, so pair it with pay_currency. Up to two decimal places."},{"name":"pay_max","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000000},"description":"Highest yearly pay. Matches postings whose pay ceiling is at most this amount, compared per year the same way as pay_min. Must not be below pay_min."},{"name":"first_seen_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"First collected by Headcount Labs on or before this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"updated_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Last changed on or before this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"curated_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Entered the final dataset on or before this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"last_fetch_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Jobs with a posting whose job source was last read completely on or after this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"last_fetch_until","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Jobs with a posting whose job source was last read completely on or before this time. Accepts an RFC 3339 timestamp or a plain date."},{"name":"application_check","in":"query","schema":{"type":"string","enum":["available","closed","broken","inconclusive"]},"description":"Jobs with a posting whose latest application check had this result. available means an application could still be started."},{"name":"application_check_since","in":"query","schema":{"oneOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}]},"description":"Jobs with a posting whose latest application check ran on or after this time. Accepts an RFC 3339 timestamp or a plain date."}],"responses":{"200":{"description":"Matching job count and snapshot watermark.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCountResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/QueryTimeout"}}}},"/v1/jobs/{jobId}":{"get":{"operationId":"getJob","summary":"Get a job by ID","description":"Returns one job with all its linked postings from the latest published jobs catalog. Responds 503 catalog_unavailable while no jobs catalog has been published.","x-applyrelay-availability":"pending_jobs_catalog","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","$ref":"#/components/schemas/JobId"},"description":"Headcount Labs job ID (lowercase UUID). A merged job redirects (308) to the job it merged into; a withdrawn job returns 410."},{"name":"fields","in":"query","description":"Comma list of the job properties to return; repeat the parameter or separate names with commas. Allowed names are job_id, currentness, stale, company_id, employer_name, title, description, work_arrangement, locations, job_first_seen_at, curated_at, job_updated_at, postings and company. job_id is always returned. Without fields the whole job is returned. An unknown name returns 400. It changes only the shape of each job, never which jobs match.","schema":{"type":"string","example":"title,employer_name,locations"}}],"responses":{"200":{"description":"A public job record with all linked postings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobDetailResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/QueryTimeout"}}}},"/v1/account/overage":{"put":{"operationId":"setOverage","summary":"Turn overage billing on or off and set its monthly limit","description":"Turns overage billing on or off for an account with an active paid subscription, and sets an optional monthly limit in US dollars. Overage is off by default. monthlyLimitUsd is a positive number with at most two decimals, up to 100000. With no limit, which is the default, overage has no ceiling. With a limit, once the month's overage dollars reach it requests stop with 429 data_limit_exceeded, nothing is billed above it, and a page that would cross it is refused whole. null clears the limit and leaving the field out keeps the stored one. An account without an active paid subscription answers 403 upgrade_required with an upgrade_url, or 403 no_active_subscription. The same change is available to agents as the set_overage MCP tool. This request is not counted against the request windows.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"enabled":{"type":"boolean"},"monthlyLimitUsd":{"type":["number","null"],"exclusiveMinimum":0,"maximum":100000,"multipleOf":0.01,"description":"Monthly overage limit in US dollars; null clears it (no limit). Omit to keep the stored value."}}}}}},"responses":{"200":{"description":"The overage setting and this month's overage use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverageStatus"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"403":{"description":"upgrade_required (no paid subscription; the error carries upgrade_url) or no_active_subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"overage_item_conflict. The subscription already carries a different overage price; contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/usage/requests":{"get":{"operationId":"listUsageRequests","summary":"List customer request events","description":"Lists the authenticated customer's admitted requests. The cursor freezes admission membership for one hour; settlement status stays current.","parameters":[{"$ref":"#/components/parameters/UsageFrom"},{"$ref":"#/components/parameters/UsageTo"},{"$ref":"#/components/parameters/UsageRouteClass"},{"$ref":"#/components/parameters/UsageApiKeyId"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Rows per page, 1-100. Defaults to 50."},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1,"maxLength":8192},"description":"The next_cursor from the previous page. Usage cursors expire after one hour."}],"responses":{"200":{"description":"A page of request events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageRequestsPage"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/usage/analytics":{"get":{"operationId":"getUsageAnalytics","summary":"Read customer daily usage","description":"Reports up to 100,000 unique events and 1,000 groups in a period of at most 31 days. Request metrics use admission day; record metrics use finalization day.","parameters":[{"$ref":"#/components/parameters/UsageFrom"},{"$ref":"#/components/parameters/UsageTo"},{"$ref":"#/components/parameters/UsageRouteClass"},{"$ref":"#/components/parameters/UsageApiKeyId"},{"name":"group_by","in":"query","schema":{"type":"string","enum":["route_class","status_class","api_key_id"]},"description":"Group the totals by route_class, status_class or api_key_id. Omit it for one overall total."}],"responses":{"200":{"description":"Daily usage groups.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageAnalytics"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/InvalidApiKey"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The report exceeded a complete-result limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/DataApiLimit"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"CompanyId":{"name":"companyId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/CompanyId"},"description":"Headcount Labs company ID (lowercase UUID). A merged company's old ID redirects (308) to its current ID."},"CompanyLimit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size, 1-100. Defaults to 50."},"CompanyCursor":{"name":"cursor","in":"query","schema":{"type":"string","minLength":1,"maxLength":2048},"description":"The next_cursor from the previous page. It pins the company release it started on."},"UsageFrom":{"name":"from","in":"query","required":true,"description":"Inclusive UTC RFC 3339 timestamp.","schema":{"type":"string","format":"date-time"}},"UsageTo":{"name":"to","in":"query","required":true,"description":"Exclusive UTC RFC 3339 timestamp; at most 31 days after from.","schema":{"type":"string","format":"date-time"}},"UsageRouteClass":{"name":"route_class","in":"query","schema":{"type":"string","enum":["jobs.list","jobs.detail","jobs.changes","jobs.count","companies.jobs","companies.list","companies.detail","companies.search","usage.requests","usage.analytics"]},"description":"Only requests of this kind, for example jobs.list, jobs.count or companies.detail."},"UsageApiKeyId":{"name":"api_key_id","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"Only requests made with this key (one of your own keys)."}},"responses":{"InvalidRequest":{"description":"The request parameters or body are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InvalidApiKey":{"description":"A valid bearer API key is required.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The company or customer-owned API key was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"DataApiLimit":{"description":"A request window or the allowance was reached.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unavailable":{"description":"The required service or publication is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"QueryTimeout":{"description":"The query did not finish within 10 seconds (code query_timeout). No records are charged. Narrow the filters, for example add a state, title, or employer, and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"JobsExport":{"type":"object","required":["export_id","status","created_at","completed_at","expires_at","record_count","snapshot_watermark","request","files"],"properties":{"export_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","completed","failed","expired"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"record_count":{"type":"integer","minimum":0},"snapshot_watermark":{"type":["string","null"]},"request":{"type":"object"},"files":{"type":"array","items":{"type":"object","required":["n","records","bytes","url"],"properties":{"n":{"type":"integer","minimum":1},"records":{"type":"integer","minimum":1},"bytes":{"type":"integer","minimum":0},"url":{"type":"string"}}}},"error":{"type":"string"}}},"CompanyId":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"JobId":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"FieldStateSourceOmitted":{"type":"object","description":"The source did not publish this field.","additionalProperties":false,"required":["state"],"properties":{"state":{"const":"source_omitted"}}},"FieldStateSourceUnmapped":{"type":"object","description":"The source published a value outside this field's vocabulary. The value stays null and evidence keeps the source's own words.","additionalProperties":false,"required":["state","value","evidence"],"properties":{"state":{"const":"source_unmapped"},"value":{"type":"null"},"evidence":{"type":"array","items":{"type":"string"}}}},"FieldStateExtractionFailed":{"type":"object","description":"The source published this field but Headcount Labs could not read it.","additionalProperties":false,"required":["state"],"properties":{"state":{"const":"extraction_failed"}}},"FieldStateKnownString":{"type":"object","additionalProperties":false,"required":["state","value"],"properties":{"state":{"const":"known"},"value":{"type":"string"}}},"FieldStateDerivedString":{"type":"object","description":"A value computed from source data by a fixed rule, never by a model. Evidence names the rule's input.","additionalProperties":false,"required":["state","value","evidence"],"properties":{"state":{"const":"derived"},"value":{"type":"string"},"evidence":{"type":"array","items":{"type":"string"}}}},"FieldStateString":{"oneOf":[{"$ref":"#/components/schemas/FieldStateKnownString"},{"$ref":"#/components/schemas/FieldStateSourceOmitted"},{"$ref":"#/components/schemas/FieldStateSourceUnmapped"},{"$ref":"#/components/schemas/FieldStateExtractionFailed"},{"$ref":"#/components/schemas/FieldStateDerivedString"}]},"FieldStateKnownWorkArrangement":{"type":"object","additionalProperties":false,"required":["state","value"],"properties":{"state":{"const":"known"},"value":{"type":"string","enum":["remote","hybrid","in_person"]}}},"FieldStateDerivedWorkArrangement":{"type":"object","description":"A value computed from source data by a fixed rule, never by a model. Evidence names the rule's input.","additionalProperties":false,"required":["state","value","evidence"],"properties":{"state":{"const":"derived"},"value":{"type":"string","enum":["remote","hybrid","in_person"]},"evidence":{"type":"array","items":{"type":"string"}}}},"FieldStateWorkArrangement":{"oneOf":[{"$ref":"#/components/schemas/FieldStateKnownWorkArrangement"},{"$ref":"#/components/schemas/FieldStateSourceOmitted"},{"$ref":"#/components/schemas/FieldStateSourceUnmapped"},{"$ref":"#/components/schemas/FieldStateExtractionFailed"},{"$ref":"#/components/schemas/FieldStateDerivedWorkArrangement"}]},"FieldStateKnownObject":{"type":"object","additionalProperties":false,"required":["state","value"],"properties":{"state":{"const":"known"},"value":{"type":"object","additionalProperties":true}}},"FieldStateDerivedObject":{"type":"object","description":"A value computed from source data by a fixed rule, never by a model. Evidence names the rule's input.","additionalProperties":false,"required":["state","value","evidence"],"properties":{"state":{"const":"derived"},"value":{"type":"object","additionalProperties":true},"evidence":{"type":"array","items":{"type":"string"}}}},"FieldStateObject":{"oneOf":[{"$ref":"#/components/schemas/FieldStateKnownObject"},{"$ref":"#/components/schemas/FieldStateSourceOmitted"},{"$ref":"#/components/schemas/FieldStateSourceUnmapped"},{"$ref":"#/components/schemas/FieldStateExtractionFailed"},{"$ref":"#/components/schemas/FieldStateDerivedObject"}]},"JobPosting":{"type":"object","additionalProperties":false,"required":["posting_id","source","source_posting_id","posting_status","posting_url","application_url","location","pay","source_posted_at","first_seen_at","last_completed_fetch_at","latest_application_check","attribution"],"properties":{"posting_id":{"description":"Headcount Labs's ID for this posting (one public listing of the job on one job source).","type":"string"},"source":{"type":"string","description":"The job source vendor, such as greenhouse or smartrecruiters."},"source_posting_id":{"description":"The job source's own ID for this posting.","type":"string"},"posting_status":{"description":"listed while the source still shows the posting; no_longer_listed once a completed fetch no longer finds it.","type":"string","enum":["listed","no_longer_listed"]},"posting_url":{"description":"The posting's public page on the job source.","$ref":"#/components/schemas/FieldStateString"},"application_url":{"description":"Where to apply for this posting, when the source gives an application link.","$ref":"#/components/schemas/FieldStateString"},"location":{"description":"The posting's location as the source published it (city, region, country). When the posting itself states a US postal code that is real and lies in the stated state, the object also has zip, the 5-digit ZIP (ZIP+4 is cut to 5). zip is absent for a city-only location, a street address without a ZIP, a remote posting and any non-US location; it is never derived from a city or a point.","$ref":"#/components/schemas/FieldStateObject"},"pay":{"description":"Pay as the source published it (minimum, maximum, currency and period), not converted.","$ref":"#/components/schemas/FieldStateObject"},"source_posted_at":{"description":"The date the job source says the posting was published.","type":["string","null"],"format":"date-time"},"first_seen_at":{"description":"When Headcount Labs first collected this posting.","type":"string","format":"date-time"},"last_completed_fetch_at":{"description":"When Headcount Labs last read the posting's job source completely.","type":["string","null"],"format":"date-time"},"latest_application_check":{"description":"Headcount Labs's latest check of whether an application can still be started (available, closed, broken or inconclusive) and when it ran.","oneOf":[{"type":"object","additionalProperties":false,"required":["result","checked_at"],"properties":{"result":{"type":"string","enum":["available","closed","broken","inconclusive"]},"checked_at":{"type":"string","format":"date-time"}}},{"type":"null"}]},"attribution":{"type":"object","description":"What the job source's rights record says about crediting it. null means the rights record does not say. When required is true, show text and link with the job.","additionalProperties":false,"required":["required","text","link"],"properties":{"required":{"description":"true when the job source asks to be credited next to the job.","type":["boolean","null"]},"text":{"description":"The credit text to show.","type":["string","null"]},"link":{"description":"The credit link to show.","type":["string","null"]}}},"source_data":{"type":"object","description":"Allowlisted source metadata, present only when requested. The source payload and internal extraction details are not published.","additionalProperties":false,"properties":{"job_location_type":{"type":["string","null"],"description":"The source's own work-location label, as published."},"source_posted_at":{"description":"The source's posted date, as published.","type":["string","null"]},"source_updated_at":{"description":"The source's own last-updated time, as published.","type":["string","null"]},"employment_type":{"description":"The source's employment type label, such as full_time, as published.","type":["string","null"]},"source_type":{"description":"The kind of job source, such as an ATS board or an employer site.","type":["string","null"]},"availability":{"description":"Whether the source shows the posting as listed.","type":"string"}}}}},"Job":{"type":"object","additionalProperties":false,"required":["job_id","currentness","stale","company_id","employer_name","title","description","work_arrangement","locations","job_first_seen_at","curated_at","job_updated_at","postings"],"properties":{"job_id":{"description":"The combined Headcount Labs job ID. One job links every posting of the same opening.","$ref":"#/components/schemas/JobId"},"merged_into_job_id":{"$ref":"#/components/schemas/JobId","description":"Present on merged-job redirects."},"currentness":{"description":"current while a linked posting is listed and accepting applications; uncertain when Headcount Labs cannot confirm that; not_current when every linked posting is no longer listed.","type":"string","enum":["current","uncertain","not_current"]},"stale":{"description":"A label published with the job. A stale job stays listed and in results; filter with stale=false to leave stale jobs out.","type":"boolean"},"company_id":{"description":"The Headcount Labs company record. Null when the job's employer is not yet linked to a company record; employer_name then carries the name the source published.","oneOf":[{"$ref":"#/components/schemas/CompanyId"},{"type":"null"}]},"employer_name":{"description":"The employer name.","$ref":"#/components/schemas/FieldStateString"},"title":{"description":"The job title.","$ref":"#/components/schemas/FieldStateString"},"description":{"description":"The job description as plain text.","$ref":"#/components/schemas/FieldStateString"},"work_arrangement":{"description":"remote, hybrid or in_person, as the source states it.","$ref":"#/components/schemas/FieldStateWorkArrangement"},"locations":{"description":"Every location of the job, combined from its linked postings. A known location value holds the address fields (street, city, region, postal_code, country); zip, the 5-digit US ZIP the posting states for that place when it states one that is real and in the stated state (the key is absent otherwise); and, when Headcount Labs could place the location, county_fips (5-digit US county FIPS code, a string such as 48453) and msa (cbsa_code, cbsa_title and type, metro or micro, of the metropolitan or micropolitan statistical area; null when the location is in no statistical area).","type":"array","items":{"$ref":"#/components/schemas/FieldStateObject"}},"job_first_seen_at":{"description":"When Headcount Labs first collected any posting of this job.","type":"string","format":"date-time"},"curated_at":{"description":"When the job first entered the final dataset.","type":"string","format":"date-time"},"job_updated_at":{"description":"When the job record last changed; sort=updated orders by this.","type":"string","format":"date-time"},"postings":{"type":"array","items":{"$ref":"#/components/schemas/JobPosting"}}}},"JobDetailResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Job"}}},"JobListResponse":{"type":"object","additionalProperties":false,"required":["data","next_cursor","snapshot_watermark"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"next_cursor":{"type":["string","null"]},"snapshot_watermark":{"type":"string","format":"date-time"}}},"JobChange":{"type":"object","required":["event_id","job_id","type","occurred_at"],"properties":{"event_id":{"type":"string"},"job_id":{"$ref":"#/components/schemas/JobId"},"type":{"type":"string","enum":["created","updated","expired"]},"occurred_at":{"type":"string","format":"date-time"},"job":{"$ref":"#/components/schemas/Job"}}},"JobsChangesResponse":{"type":"object","required":["data","resume_cursor","has_more","snapshot_watermark"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JobChange"}},"resume_cursor":{"type":"string"},"has_more":{"type":"boolean"},"snapshot_watermark":{"type":"string","format":"date-time"}}},"JobCountResponse":{"type":"object","required":["count","snapshot_watermark"],"properties":{"count":{"type":"integer","minimum":0},"snapshot_watermark":{"type":"string","format":"date-time"}}},"Company":{"type":"object","additionalProperties":false,"required":["company_id","name","country","status","region","address_source","identifiers","industries"],"properties":{"company_id":{"$ref":"#/components/schemas/CompanyId"},"name":{"type":"string"},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 code, or null when the registry country is unknown."},"status":{"type":"string","enum":["active","retired","merged"]},"region":{"type":["string","null"],"description":"State or province code from the same government address as country, or null when unknown."},"address_source":{"type":["string","null"],"enum":["sec","dol_form5500",null],"description":"Which government address gave country and region: sec (SEC business address) or dol_form5500 (Form 5500 plan sponsor address). Null when no government address is known."},"identifiers":{"type":"array","description":"Public registry identifiers, each from a US-government public source. Empty when none is known.","items":{"type":"object","additionalProperties":false,"required":["scheme","value","exchange","source"],"properties":{"scheme":{"type":"string","enum":["sec_cik","ein","uei","ticker"],"description":"sec_cik is the 10-digit SEC Central Index Key; ein the 9-digit IRS Employer Identification Number; uei the 12-character SAM.gov Unique Entity ID; ticker a stock symbol from the SEC's company ticker list."},"value":{"type":"string"},"exchange":{"type":["string","null"],"description":"The listing exchange for a ticker when the SEC gives one, otherwise null."},"source":{"type":"string","enum":["sec","dol_form5500","sam_gov"]}}}},"industries":{"type":"array","description":"Industry codes, each from a US-government public source. Empty when none is known.","items":{"type":"object","additionalProperties":false,"required":["system","code","source"],"properties":{"system":{"type":"string","enum":["naics","sic"]},"code":{"type":"string","pattern":"^[0-9]{2,6}$"},"source":{"type":"string","enum":["sec","dol_form5500","sam_gov"]}}}}}},"CompanyPage":{"type":"object","additionalProperties":false,"required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"next_cursor":{"type":["string","null"]}}},"CompanySearchRequest":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Case-insensitive canonical-name substring after trimming."},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 code, case-insensitive."},"status":{"type":"string","enum":["active","retired","merged"]},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50},"cursor":{"type":"string","minLength":1,"maxLength":2048}}},"ErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}},"UsageRequestRow":{"type":"object","additionalProperties":false,"required":["request_id","api_key_id","route_class","admitted_at","finalized_at","state","http_status","request_charged","records_returned","policy_id","policy_version","settlement_policy_id","settlement_policy_version"],"properties":{"request_id":{"type":"string"},"api_key_id":{"type":"string"},"route_class":{"type":"string"},"admitted_at":{"type":"string","format":"date-time"},"finalized_at":{"type":["string","null"]},"state":{"type":"string"},"http_status":{"type":["integer","null"]},"request_charged":{"type":"boolean"},"records_returned":{"type":"integer","minimum":0},"policy_id":{"type":["string","null"]},"policy_version":{"type":["integer","null"]},"settlement_policy_id":{"type":["string","null"]},"settlement_policy_version":{"type":["integer","null"]}}},"OverageStatus":{"type":"object","required":["overage_enabled","overage_monthly_limit_usd","overage_limit_remaining_usd","overage_jobs_used","overage_usd"],"properties":{"overage_enabled":{"type":"boolean"},"overage_monthly_limit_usd":{"type":["number","null"],"description":"The monthly overage limit in US dollars; null when the customer set none."},"overage_limit_remaining_usd":{"type":["number","null"],"description":"Dollars of the limit not yet used this month; null when there is no limit."},"overage_jobs_used":{"type":"integer","description":"Jobs used this UTC month past the included allowance."},"overage_usd":{"type":"number","description":"This month's overage so far, rounded up to the cent."}}},"UsageRequestsPage":{"type":"object","additionalProperties":false,"required":["data","next_cursor","admissions_captured_at"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageRequestRow"}},"next_cursor":{"type":["string","null"]},"admissions_captured_at":{"type":"string","format":"date-time"}}},"UsageDailyGroup":{"type":"object","additionalProperties":false,"required":["day","group","request_events","charged_requests","pending_requests","rate_limited_requests","usage_limited_requests","http_status_2xx","http_status_3xx","http_status_4xx","http_status_5xx","error_rate","returned_records","job_records_returned","company_records_returned"],"properties":{"day":{"type":"string","format":"date"},"group":{"type":"string"},"request_events":{"type":"integer"},"charged_requests":{"type":"integer"},"pending_requests":{"type":"integer"},"rate_limited_requests":{"type":"integer"},"usage_limited_requests":{"type":"integer"},"http_status_2xx":{"type":"integer"},"http_status_3xx":{"type":"integer"},"http_status_4xx":{"type":"integer"},"http_status_5xx":{"type":"integer"},"error_rate":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Share of admitted requests in this day and group that returned a 4xx or 5xx response, rounded to four decimal places; null when no requests were admitted."},"returned_records":{"type":"integer"},"job_records_returned":{"type":"integer"},"company_records_returned":{"type":"integer"}}},"UsageAnalytics":{"type":"object","additionalProperties":false,"required":["query_timestamp","time_basis","group_by","data"],"properties":{"query_timestamp":{"type":"string","format":"date-time"},"time_basis":{"type":"object","additionalProperties":false,"required":["requestMetrics","returnedRecordMetrics","pendingAndRejections"],"properties":{"requestMetrics":{"type":"string","const":"admitted_at_utc_day"},"returnedRecordMetrics":{"type":"string","const":"finalized_at_utc_day"},"pendingAndRejections":{"type":"string","const":"included_on_admission_day"}}},"group_by":{"type":["string","null"],"enum":["route_class","status_class","api_key_id",null]},"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageDailyGroup"}}}}}}}