Market insights

get_market_insights answers questions about the market as a whole, such as:

• "How many senior vs mid-level roles are open in London?"
• "What's the median data engineer salary in Germany, by work type?"

It returns ready-to-chart numbers in one call, so your assistant doesn't have to page through search results and count. Each call is one market insight query, however many rows it returns. You get 500 a day.

How it works

Choose:

• What to group by (group_by): experience level, work type, contract type, company, skill, city, country, industry, job title, or posting week or month.
• What to measure (metric): count for numbers of open roles and their share, or salary for median annual salaries with quartiles.
• Optionally, a second dimension (breakdown_by): experience level, work type, contract type or country. This gives one row per combination, for stacked or grouped charts.
• Filters: the same as search_leads, such as title, location, skills and seniority.

Parameter	Values	Default
group_by	experience_level, work_type, employment_type, company, skill, city, country, industry, title, posted_week, posted_month	Required
metric	count, salary	count
breakdown_by	experience_level, work_type, employment_type, country. Must differ from group_by. Not available with group_by: "title"	None
currency	GBP, EUR, USD, for salary figures	GBP
limit	1–50 groups	10

Output

Field	Description
metric, group_by, breakdown_by	What was computed
unit	open roles, or for salaries for example EUR per year (median of annualised salary midpoints)
total_matching_roles	Open roles matching the filters
rows	One per group, or per group and series with a breakdown
chart_hint	Suggested chart: bar, pie, line, stacked_bar or grouped_bar
filters_applied	The filters used, so the assistant can describe them
notes	Caveats for this result
quota	Today's market insight quota after the call

Each row has:

Field	Description
label	The group, for example Senior, Python, London, United Kingdom or 2026-09
series	The breakdown_by value, when you asked for one
value	Count of open roles, or the median annual salary
share	Count only: value divided by total_matching_roles
sample_size	Salary only: roles with a usable salary in this group
p25, p75	Salary only: lower and upper quartile

How the numbers are computed

• Open roles only. Every figure is about roles that are open now.
• Multi-value dimensions. A role can have several skills, cities, countries or industries, so it counts once in each. With these dimensions, shares can add up to more than 1.
• Missing values. Roles without a value for experience level, work type or contract type appear as Unspecified.
• Job titles. Titles are grouped by role, without seniority, so "Senior Data Engineer" and "Data Engineer" count together under "Data Engineer". To compare seniority, group by experience_level and filter by title.
• Time buckets. posted_week labels start on Monday (YYYY-MM-DD) and posted_month labels look like YYYY-MM. They show the most recent periods, oldest first, and count roles by posting date. Roles that have since closed are not included, so older buckets look smaller than they were at the time.
• Salaries:
  • Only roles that publish a salary count.
  • Each role's salary is the midpoint of its range. It's converted to a yearly figure from the posted period (hour, day, week or month) and into the requested currency at fixed reference exchange rates.
  • Yearly values outside 8,000–1,000,000 are left out as likely data errors.
  • Groups with fewer than 3 salaried roles are left out.
• Breakdowns return the top limit groups and up to 12 series.

Examples

Senior vs mid-level roles in London

{ "group_by": "experience_level", "location": "London" }

Example response (numbers are illustrative):

{
  "metric": "count",
  "group_by": "experience_level",
  "breakdown_by": null,
  "unit": "open roles",
  "total_matching_roles": 4210,
  "rows": [
    { "label": "Senior", "series": null, "value": 1630, "share": 0.3872, "sample_size": null, "p25": null, "p75": null },
    { "label": "Mid", "series": null, "value": 1385, "share": 0.329, "sample_size": null, "p25": null, "p75": null },
    { "label": "Lead", "series": null, "value": 540, "share": 0.1283, "sample_size": null, "p25": null, "p75": null },
    { "label": "Entry", "series": null, "value": 402, "share": 0.0955, "sample_size": null, "p25": null, "p75": null },
    { "label": "Unspecified", "series": null, "value": 203, "share": 0.0482, "sample_size": null, "p25": null, "p75": null },
    { "label": "Executive", "series": null, "value": 50, "share": 0.0119, "sample_size": null, "p25": null, "p75": null }
  ],
  "chart_hint": "pie",
  "filters_applied": { "location": "London" },
  "notes": [],
  "quota": { "used": 1, "limit": 500, "remaining": 499, "resets_at": "2026-10-15T00:00:00+00:00" }
}

Median data engineer salary in Germany, by work type

{
  "metric": "salary",
  "group_by": "work_type",
  "title": "data engineer",
  "location": "Germany",
  "currency": "EUR"
}

Each row's value is the median, with p25, p75 and sample_size alongside.

Seniority mix by country

{ "group_by": "country", "breakdown_by": "experience_level" }

Rows come in pairs such as { "label": "Germany", "series": "Senior", "value": ... }. chart_hint is stacked_bar.

Weekly trend for Python roles in the UK

{ "group_by": "posted_week", "skills": ["Python"], "location": "United Kingdom", "limit": 12 }

Returns the last 12 weeks, oldest first, with chart_hint line.

Who is hiring the most React engineers in Berlin

{ "group_by": "company", "skills": ["React"], "location": "Berlin", "limit": 15 }

To see a company's roles, follow up with search_companies or search_leads using its id.

Tips

• Start broad and add filters. A very broad query can time out (query_timeout). Adding a location, title or posted_within_days fixes it.
• Use get_market_insights for "how many" questions. It costs one query, while counting search results uses an explore per role.
• Use get_filter_options to see valid filter values and the most common industries.