getPostingTrends

Returns posting volume, posting duration, hiring-company counts, posting compensation metrics, and growth rates for the requested role and market. Use this as the primary SIQ metrics tool when the goal is to quantify current labor-market activity.

Tool-specific notes

• companyName can be provided when the analysis should be limited to a specific employer.
• isShowBaseDistribution controls whether the baseDistribution histogram is included in the response. The default behavior is to include it.
• onlyPosted controls whether the result set includes only salary-disclosed postings or all postings. The default behavior is true.

Input Schema

{
  "type": "object",
  "properties": {
    "country": {
      "description": "Country code, e.g. 'USA', 'GBR', 'CAN'",
      "type": "string"
    },
    "jobTitle": {
      "description": "Job title to analyse trends for, e.g. 'Data Scientist' (provide at least one of jobTitle, jobDescription, or postingKeyword)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "jobDescription": {
      "description": "Optional free-text role context used to improve title/role matching",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "postingKeyword": {
      "description": "Keyword to search across postings (alternative to jobTitle/jobDescription)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "startDate": {
      "description": "Start date in YYYY-MM-DD format (optional, defaults to 90 days ago)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "endDate": {
      "description": "End date in YYYY-MM-DD format (optional, defaults to today)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "state": {
      "description": "State or province (optional)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "city": {
      "description": "City name for geographic filtering (optional)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "zipCode": {
      "description": "ZIP or postal code for geographic filtering (optional)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "metro": {
      "description": "Metro area name for geographic filtering (optional), e.g. 'New York-Newark-Jersey City'",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "naicsCode": {
      "description": "NAICS industry code filter (optional)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "companyFteSize": {
      "description": "Company FTE size range use actual value to filter (optional)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "companyName": {
      "description": "Filter to specific company name (optional)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    },
    "onlyPosted": {
      "description": "Only return salary-disclosed postings (optional)",
      "type": "boolean",
      "default": true
    },
    "isShowBaseDistribution": {
      "description": "Include the BaseDistribution salary histogram in the response (optional, defaults to true). Set to false to omit BaseDistribution from the response.",
      "type": "boolean",
      "default": true
    },
    "sessionId": {
      "description": "Session ID for conversation context (optional)",
      "type": [
        "string",
        "null"
      ],
      "default": null
    }
  },
  "required": [
      "country"
  ]
}

Output Schema

{
  "datasetRoutedTo": "LaborMarketData",
  "matchRating": "Potential",
  "normalizedGeography": {
    "country": "USA",
    "region": "South",
    "state": "TX"
  },
  "normalizedIndustry": "All Industries",
  "normalizedCompanySize": "All FTEs",
  "normalizedDateRange": {
    "start": "2026-02-27",
    "end": "2026-05-28"
  },
  "companyName": "Amazon.com Inc",
  "numberOfPostings": 2,
  "averagePostingDuration": 20,
  "numberOfHiringCompanies": 1,
  "historicalHiringCompanies": 1,
  "posting25": 148626.75,
  "posting50": 156184.5,
  "posting75": 163742.25,
  "percentRemote": 0,
  "percentSignOnBonus": 0,
  "growthRates": {
    "postingMedianRate": -5.1703096539162114,
    "numberOfPostingRate": 0,
    "hiringCompanyRate": 0,
    "averageDurationRate": -57.89473684210527
  },
  "baseDistribution": [
    {
      "baseDistributionId": 1,
      "rangeMin": 0,
      "rangeMax": 156184.5,
      "numberOfPostings": 1,
      "numberOfHiringCompanies": 1
    },
    {
      "baseDistributionId": 2,
      "rangeMin": 156184.5,
      "rangeMax": 312369,
      "numberOfPostings": 1,
      "numberOfHiringCompanies": 1
    }
  ],
  "benchmarkJobTitle": "Product Design Engineer I",
  "socCode": "17-2199",
  "socTitle": "Engineers, All Other",
  "JobFamilyName": "Engineering Design & Development",
  "jobLevelName": "Entry (I)",
  "skills": "CAD Software | Computer-Aided Engineering (CAE) Software | Design Documentation | Product Design | Product Requirements | Testing Results Analysis",
  "onlyPosted": true,
  "summaryText": "For Product Design Engineer I in TX, USA during 2026-02-27 to 2026-05-28, total posting volume was 2. Compared with the prior period, postings are stable (0.0%). Average posting duration was 20.0 days. Demand appears notably low versus typical hiring levels in this market.",
  "executionId": "exec_1779980170951_8206a7de8e0b4a0f86c4fc36ced92f05",
  "nextActions": [
    "Get a full labor market summary → summarizeLaborMarket",
    "See which skills are trending for this role → getTrendingSkills"
  ]
}