---
title: "Facet the jobs dataset (hiring market aggregates)"
method: GET
path: "/datasets/jobs/facets"
tags: ["Datasets"]
---

# Facet the jobs dataset (hiring market aggregates)

`GET /datasets/jobs/facets`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/datasets/jobs/facets`
- Auth: API key in header `x-api-key`

Aggregations over all open postings: top companies hiring, breakdown by provider (every provider filterable via /datasets/jobs/search's `provider` param), department, location, employment type, skill, benefit, education, security clearance, seniority, and ESCO/ISCO job family, plus the remote share — a live hiring-market snapshot. Seniority uses one mutually exclusive value: `entry`, `mid`, or `senior`; ambiguous occupations are omitted from job-family buckets.

## Query parameters

- `size` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- DatasetsJobsFacetResponseDoc
  - `code` integer
  - `data` DatasetsJobsFacetResponse
    - `facets` EsJobPostingFacets
      - `by_ai_tool` EsFacetItem[]: ByAITool counts canonical AI tool and platform names mentioned in open job postings.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_benefit` EsFacetItem[]: ByBenefit, BySecurityClearance, and ByEducationLevel count canonical requirements and offerings mentioned in open job postings.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_department` EsFacetItem[]: Open posting counts by department.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_education_level` EsFacetItem[]: Open posting counts by education level mentioned in the posting.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_employment_type` EsFacetItem[]: Open posting counts by employment type, for example `Full-time`.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_job_family` EsFacetItem[]: ByJobFamily counts conservative ESCO/ISCO occupation-family classifications; postings without sufficient evidence are omitted.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_location` EsFacetItem[]: Open posting counts by location.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_provider` EsFacetItem[]: Open posting counts by job source.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_security_clearance` EsFacetItem[]: Open posting counts by security clearance level mentioned in the posting.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_seniority` EsFacetItem[]: BySeniority counts the mutually exclusive entry/mid/senior classification over open postings.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `by_skill` EsFacetItem[]: BySkill counts canonical ESCO skill labels mentioned in open job postings.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `remote_open` integer: Number of open postings marked remote.
      - `top_companies` EsFacetItem[]: Companies with the most open postings, with the posting count for each.
        - `count` integer: Number of open job postings with this value.
        - `key` string: Facet value, for example a company, department or location name.
      - `total_open` integer: Total number of open postings.
  - `msg` string

## Other responses

- `400`: Bad Request
- `500`: Internal Server Error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)