Filters

Filters structured constraints applied to a tool request. They narrow the data included in an analysis request by allowing you to focus on supported dimensions for the selected dataset and tool, such as occupations, skills, companies, locations, education levels, salary ranges, or time periods.

For example, a filter can limit a request to a time range, occupation, location, skill, company, salary range, or education level.

👉 Supported filters vary by dataset and tool. Before building a request, use tool_info to view the supported dimensions, operators, and filters for the selected dataset and tool.

Filter Shape

A filter is an object whose keys are dimension names. The supported filter structure for each dimension is defined by the schema returned by tool_info.

Most taxonomy-backed filters use this shape:

{
  "skill": {
    "level": 1,
    "values": ["e15b"],
    "operator": "or"
  }
}

The operator property is optional and is supported only by certain dimensions. If you do not specify an operator, the dimension's default behavior is applied.

Include Semantics

For classifiable taxonomy and structured facet dimensions, the valuesrepresents included values.

{
  "skill": {
    "level": 3,
    "values": ["KS126XS6CQCFGC3NG79X"]
  }
}

This filter includes records associated with the specified skill ID.

Exclude Semantics

Lightcast MCP does not currently support a general exclude operator. Exclusion is supported only for certain boolean flag dimensions, where a value of false excludes matching records.

{
  "company_flags": {
    "level": 1,
    "values": {
      "is_fortune_100": false,
      "is_fortune_500": true
    }
  }
}

In this example, is_fortune_500: true includes Fortune 500 companies, while is_fortune_100: false excludes Fortune 100 companies. Flag predicates are combined.

Required Time Filter For Job Postings

A time is required for all job_postings analysis request.

{
  "time": {
    "level": 1,
    "values": {
      "start": "2024-01",
      "end": "2024-12",
      "postingType": "posted"
    }
  }
}

The postingType value can be active, posted, or expired.

Profile Time Filter

The time filter in the profiles dataset uses profile last-updated dates to limit the results returned by a request.

{
  "time": {
    "level": 1,
    "values": {
      "lastUpdatedStart": "2020",
      "lastUpdatedEnd": "2024"
    }
  }
}

Range Filters

Range filters use lowerBound, upperBound, or both to define the range of values included in the analysis.

{
  "experience": {
    "level": 1,
    "values": {
      "lowerBound": 2,
      "upperBound": 5
    }
  }
}

compensation_salary and experience support numeric range values where available. education_grad_year supports year start and end values for profiles.

Validation

Lightcast MCP validates filters against the selected dataset and tool schema before processing a request. The following validation errors can cause a request to be rejected: