List

Overview

The list tool returns a small sample of individual job postings from the job_postings dataset. Use it when an agent or analyst needs representative records rather than aggregate metrics.

Common Use Cases

Use list tool to answer questions such as:

Use Case	Example
Posting examples	Show example postings matching this filter.
Posting URLs and titles	Return posting URLs and titles for the most relevant results.
Posting text review	Inspect raw posting text for a filtered job market.
Qualitative review	Inspect representative postings after aggregate analysis.
Analyst validation	Verify that a filter returns the expected types of job postings.
Evidence gathering	Collect posting titles, company names, URLs, salaries, or posting content for further analysis.

Supported Datasets

The list tool supports the following datasets.

Dataset	Supported	Notes
Job Posting	Yes	Requires a `time` filter.
Profile	No	Use aggregate profile tools instead.

Inputs

The tool accepts the following inputs.

Input	Description
`dataset`	Must be `job_postings`.
`filter`	Job posting filters are used to narrow the results. A time filter is required.
`fields`	One or more posting fields to return.
`order`	The field used to sort results. Supported values includes `postings.field.score` or `postings.field.posted`.
`limit`	Optional result limit from 1 to 5. Default is 1.

Supported fields include: postings.field.id, postings.field.posted, postings.field.expired, postings.field.body, postings.field.city_name, postings.field.company_name, postings.field.title_raw, postings.field.url, postings.field.active_urls, postings.field.score, and postings.field.salary.

Select only the fields required for your analysis to keep responses focused and easier to process.

Example Request

{
  "dataset": "job_postings",
  "filter": {
    "time": {
      "level": 1,
      "values": {
        "start": "2024-01",
        "end": "2024-12",
        "postingType": "posted"
      }
    }
  },
  "fields": [
    "postings.field.title_raw",
    "postings.field.company_name",
    "postings.field.url"
  ],
  "order": "postings.field.score",
  "limit": 2
}

Outputs

The response returns matching job postings and summary information about the result set.

Output	Description
`postings`	Array of posting records containing the requested fields.
`totalResults`	Total matching unique postings reported by the backend result set.

The returned postings can be used to review individual records, validate filters, or gather examples for further analysis.

Example Response

{
  "postings": [
    {
      "postings.field.title_raw": "Software Developer",
      "postings.field.company_name": "Example Employer",
      "postings.field.url": "https://example.com/posting"
    }
  ],
  "totalResults": 1250
}