count_jobs

Count the current jobs matching the filters, without listing them. This is the live count: it reads the job database as it is now, so use it for "how many jobs" and "which employers are hiring" questions, and prefer its numbers over market_lookup and market_breakdown, which read a daily snapshot. No account needed. To answer "which companies are hiring for X" or "how are these jobs split by ...", pass group_by: employer (company works too), work_arrangement (remote, hybrid or in_person), title, state (US), city (metro works too), country or employment_type. The answer then also has group_by, groups (the top 25 values by number of matching jobs, each with value and jobs), groups_from_jobs (how many matching jobs were grouped, at most 1,000, taken in the default list order), groups_sampled (true when more jobs matched than were grouped, so the counts are from a sample) and groups_unknown_jobs (grouped jobs with no known value). A job with several locations or postings can count under more than one value. group_by employer keeps its own keys: employers (each with employer_name, company_id and jobs), employers_from_jobs, employers_sampled and employers_unknown_jobs. When a filter is too broad to count exactly in time, count is an estimate: the answer then has count_is_estimate: true, count_margin (the 95% range either side of count) and count_note.

read-only

Argument	Type	Description
filters	object
group_by	string	Break the matching jobs down by employer (company), work_arrangement, title, state, city (metro), country or employment_type.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "filters": {
      "type": "object",
      "default": {},
      "properties": {
        "q": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 200
              },
              "maxItems": 10
            }
          ],
          "description": "Words matched against title and description, ranked by relevance. Every word must match; for a list of skills where any may match, use description_advanced with OR, for example python OR sql OR \"data analysis\"."
        },
        "msa": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "city": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "City name."
        },
        "near": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "A US place to search around: a ZIP code (78701), a city with its state (Austin, TX), or latitude,longitude. Use with radius_miles."
        },
        "stale": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "state": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "US state, two letters (CA) or full name."
        },
        "title": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "Words in the job title."
        },
        "active": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "job_id": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "remote": {
          "type": "boolean",
          "description": "true is the same as work_arrangement=remote."
        },
        "source": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "company": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "Company name."
        },
        "country": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 16384
            },
            {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 200
              }
            }
          ],
          "description": "One or more two-letter country codes, comma-separated or as an array (US,CA)."
        },
        "has_pay": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "pay_max": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "pay_min": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "Lowest yearly pay, in pay_currency (default USD). Hourly pay is about yearly / 2,080, so $45 an hour is about 93,600."
        },
        "location": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "company_id": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "posting_id": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "currentness": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "description": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "remote_type": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "source_type": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "has_location": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "pay_currency": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "posted_since": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "Date (YYYY-MM-DD) or ISO time; jobs posted on or after it."
        },
        "posted_until": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "radius_miles": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "Miles from near, 1-100 (default 25)."
        },
        "source_class": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "curated_since": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "curated_until": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "updated_since": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "updated_until": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "company_linked": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "exclude_source": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "posting_status": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "title_advanced": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ]
        },
        "employment_type": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 16384
            },
            {
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 200
              }
            }
          ],
          "description": "One or more employment type values, comma-separated or as an array."
        },
        "has_description": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "has_posting_url": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "published_since": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "first_seen_since": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "Date (YYYY-MM-DD) or ISO time; jobs we first found on or after it. For a daily check for new jobs, pass the time of the last check."
        },
        "first_seen_until": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "last_fetch_since": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "last_fetch_until": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "work_arrangement": {
          "anyOf": [
            {
              "$ref": "#/properties/filters/properties/q/anyOf/0"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/1"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/2"
            },
            {
              "$ref": "#/properties/filters/properties/q/anyOf/3"
            }
          ],
          "description": "remote, hybrid or in_person; comma-separate several."
        },
        "application_check": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "source_posting_id": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "has_application_url": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "description_advanced": {
          "$ref": "#/properties/filters/properties/title_advanced"
        },
        "application_check_since": {
          "$ref": "#/properties/filters/properties/title_advanced"
        }
      },
      "additionalProperties": false
    },
    "group_by": {
      "enum": [
        "employer",
        "company",
        "work_arrangement",
        "title",
        "state",
        "city",
        "metro",
        "country",
        "employment_type"
      ],
      "type": "string",
      "description": "Break the matching jobs down by employer (company), work_arrangement, title, state, city (metro), country or employment_type."
    }
  },
  "additionalProperties": false
}

get_job

Get a job by its job_id. No account needed. By default the answer has the same compact shape search_jobs returns (rank 1, job_id, job_ad, company_id, locations, work_arrangement, pay, posted_at, first_seen_at, posting_url, apply_url) with the whole description in job_ad.description, currentness, stale and last_checked_at (is it still open, and when was it last checked), and every linked posting in postings (status, last_fetched_at, application_check). Pass view: "full" for every field as the REST API returns it. Use fields to select top-level job properties; job_id is always included.

read-only

Argument	Type	Description
view	string	compact (default): the same summary search_jobs returns, plus the whole description, whether the job is still open, when it was last checked, and the linked postings. full: every field of the job, as the REST API returns it.
fields	any	Top-level job properties as a comma-separated string or field array; job_id is always included.
job_id*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "job_id"
  ],
  "properties": {
    "view": {
      "enum": [
        "compact",
        "full"
      ],
      "type": "string",
      "default": "compact",
      "description": "compact (default): the same summary search_jobs returns, plus the whole description, whether the job is still open, when it was last checked, and the linked postings. full: every field of the job, as the REST API returns it."
    },
    "fields": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200,
          "minLength": 1
        },
        {
          "type": "array",
          "items": {
            "enum": [
              "job_id",
              "currentness",
              "stale",
              "company_id",
              "employer_name",
              "title",
              "description",
              "work_arrangement",
              "locations",
              "job_first_seen_at",
              "curated_at",
              "job_updated_at",
              "postings",
              "company"
            ],
            "type": "string"
          },
          "minItems": 1
        }
      ],
      "description": "Top-level job properties as a comma-separated string or field array; job_id is always included."
    },
    "job_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}

list_fields

Find the search_jobs filters and the job fields that match some keywords, with each one's type and a short description. Pass words such as ["pay", "remote"]; no keywords lists everything. kind is filter (pass it in search_jobs filters) or field (a property of each returned job; postings[].x is a property of each linked posting). A field state is an object whose state says whether the source published the value (known), Atlas derived it, the source omitted it, or extraction failed.

read-only

Argument	Type	Description
keywords	array

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "keywords": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100,
        "minLength": 1
      },
      "default": [],
      "maxItems": 20
    }
  },
  "additionalProperties": false
}

market_breakdown

Rank the values of one dimension (by: title, state, metro, city, company, seniority, employment_type or remote) by jobs, pay or another figure, over all jobs or inside one filter, such as which states pay Software Engineers the most (by=state, title=Software Engineer, sort=pay_median). Answers come from a daily snapshot of open US jobs and give their as_of date; for current job counts or the employers hiring right now, count_jobs is the live source. Cells with fewer than 30 jobs are left out. No account needed.

read-only

Argument	Type	Description
by	string	breakdown only: what to rank (title, state, metro, city, company, seniority, employment_type or remote; place means state).
role	string	A standard job title such as "Registered Nurse" or "Software Engineer"; leave out for every job. Same as title.
sort	string	breakdown only: jobs (the default), pay_median, pay_p75, pay_p90, share_with_pay, remote_share, new_7_days or new_30_days.
limit	integer	breakdown rows or dimension values to return.
place	string	US (the default), a state code such as TX, a state name, a metro area such as "Austin-Round Rock-Georgetown, TX" or a city such as "Austin, TX" (cities and metros only for lookup, breakdown and negotiate).
title	string	A standard job title; lookup, breakdown and negotiate match more than 6,000 titles. Same as role.

market_dimensions

List what market_lookup, market_breakdown and salary_range accept: the dimensions, how many values each has and the metrics; with dimension (and optionally q) the values of that dimension, such as the metro names. No account needed.

read-only

Argument	Type	Description
q	string	dimensions only: search the values of dimension.
limit	integer	breakdown rows or dimension values to return.
dimension	string	dimensions only: list the values of this dimension.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 80,
      "description": "dimensions only: search the values of dimension."
    },
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "breakdown rows or dimension values to return."
    },
    "dimension": {
      "type": "string",
      "maxLength": 30,
      "description": "dimensions only: list the values of this dimension."
    }
  },
  "additionalProperties": true
}

market_lookup

Job count, pay percentiles, share of jobs showing pay, remote/hybrid/in-person shares, posting age, new postings or top employers for up to two of title, place, company, seniority, employment_type and remote, such as the pay range for Registered Nurses in Texas. Leave metric out for every figure. Answers come from a daily snapshot of open US jobs and give their as_of date; for current job counts or the employers hiring right now, count_jobs is the live source. Cells with fewer than 30 jobs are left out. No account needed.

read-only

Argument	Type	Description
role	string	A standard job title such as "Registered Nurse" or "Software Engineer"; leave out for every job. Same as title.
place	string	US (the default), a state code such as TX, a state name, a metro area such as "Austin-Round Rock-Georgetown, TX" or a city such as "Austin, TX" (cities and metros only for lookup, breakdown and negotiate).
title	string	A standard job title; lookup, breakdown and negotiate match more than 6,000 titles. Same as role.
metric	string	lookup only: job_count, pay, pay_share, work_arrangement, posting_age, new_postings or top_employers; leave out for all of them.
remote	string	remote, hybrid or in_person (lookup and breakdown).
company	string	An employer name (lookup and breakdown).

salary_range

What salary to ask for: for a title, a place (default US) and an optional seniority, the 25th, 50th, 75th and 90th percentile of posted pay, the sample size and a plain recommendation. Answers come from a daily snapshot of open US jobs and give their as_of date; for current job counts or the employers hiring right now, count_jobs is the live source. Cells with fewer than 30 jobs are left out. No account needed.

read-only

Argument	Type	Description
role	string	A standard job title such as "Registered Nurse" or "Software Engineer"; leave out for every job. Same as title.
place	string	US (the default), a state code such as TX, a state name, a metro area such as "Austin-Round Rock-Georgetown, TX" or a city such as "Austin, TX" (cities and metros only for lookup, breakdown and negotiate).
title	string	A standard job title; lookup, breakdown and negotiate match more than 6,000 titles. Same as role.
seniority	string	intern, entry, senior, lead, manager, director or executive, read from the job title (lookup, breakdown, negotiate).

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "role": {
      "type": "string",
      "maxLength": 120,
      "description": "A standard job title such as \"Registered Nurse\" or \"Software Engineer\"; leave out for every job. Same as title."
    },
    "place": {
      "type": "string",
      "maxLength": 60,
      "description": "US (the default), a state code such as TX, a state name, a metro area such as \"Austin-Round Rock-Georgetown, TX\" or a city such as \"Austin, TX\" (cities and metros only for lookup, breakdown and negotiate)."
    },
    "title": {
      "type": "string",
      "maxLength": 120,
      "description": "A standard job title; lookup, breakdown and negotiate match more than 6,000 titles. Same as role."
    },
    "seniority": {
      "type": "string",
      "maxLength": 40,
      "description": "intern, entry, senior, lead, manager, director or executive, read from the job title (lookup, breakdown, negotiate)."
    }
  },
  "additionalProperties": true
}

search_docs

Ask a question about Headcount Labs (filters, limits, MCP setup, errors) and get the best-matching sections of the headcountlabs.com docs, each with its URL. Works without an account.

read-only

Argument	Type	Description
limit	integer
question*	string

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "question"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 5,
      "maximum": 10,
      "minimum": 1
    },
    "question": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1
    }
  },
  "additionalProperties": false
}

search_jobs

Search current job postings by keyword, title, company, place, pay, date and more. No account needed. Call list_fields to find the filter names. Country and employment_type accept comma-separated values or arrays and match any listed value. Pages return up to 50 jobs (limit, default 10), or up to 10 jobs when descriptions is "full"; a larger limit is refused. Pass next_cursor as cursor to see the next page. One search shows up to 250 jobs in total (the last page is shortened to fit), so narrow it with filters to find the right ones; count_jobs tells you how many jobs match without listing them. sort is relevance (best match) or updated (most recently updated). By default each job is a compact summary: rank, job_id, job_ad (the employer-written title, employer and a 200-character snippet of the description), company_id, locations, work_arrangement, pay (min, max, currency, period), posted_at, first_seen_at, posting_url and apply_url. For every field of each job pass view: "full" (descriptions cut to 400 characters, or descriptions: "full" for the whole text), name the top-level properties you need in fields (job_id is always included), or call get_job for one job. You choose how much description each job gets: descriptions: "snippet" (the default) gives a short preview and allows up to 50 jobs per page; descriptions: "full" gives the whole text but allows only 10 jobs per page. To read the full text of just a few jobs, search with snippets, then call get_job on the ones you want. Leave description out of fields to drop it entirely. For job titles, title matches the words as one phrase in that order, so "senior software engineer" misses "Software Engineer, Senior"; title_advanced matches words in any order with AND, OR and NOT, for example senior AND ("software engineer" OR "software developer"), and usually finds more.

read-only

Argument	Type	Description
sort	string
view	string	compact (default): one short summary per job. full: every field of every job, as the REST API returns it.

Headcount Labs

Try it

count_jobs Read-only

Headcount Labs

Try it

count_jobs Read-only

Tools (9)