Ad volume and its trend

Ad volume and its trend

Call: GET /v1/postings
Price: Uses credits (see each response's X-Credits-Charged)
Available: soft launch
Contract: https://api.gwix.ai/docs/reference

What it's for

Count job ads first posted, by period, for any combination of company, location, industry, role and level, with optional change over time.

Use it when

• "How many ads did X post?" "Is hiring for Y rising or falling in Z?"
• Comparing demand across places, companies or periods.

Inputs

Headers: Idempotency-Key, GWIX-Agent-Id, GWIX-On-Behalf-Of.

What comes back

rows, meta, paging. If an input is ambiguous: status: needs_disambiguation with candidates, the missing input and a retry_with template (no charge).

Rules

What an ad is. An ad is one de-duplicated job advertisement within a dataset. Ads are not de-duplicated across different partners' datasets. Counts are ads first posted in the period.

Periods. Periods are whole Monday-Sunday weeks. A month is 4 weeks, a quarter 13, a year 52, anchored to complete weeks ending on or before the period's last day. There are no partial periods; the current week is never included until it is complete. Ask for periods with interval plus start_period and end_period labels (custom date ranges are not available at launch).

Zeros and coverage. coverage_status: covered means GWIX sources were watching, so a zero means no ads were observed. not_covered means GWIX cannot say; values are null. Periods and named values are always returned, even when zero; unnamed zero rows are omitted and counted in meta.zero_rows_omitted.

Geography. Statistics are built at metro level. Location filters work at metro, state and country at launch; a city or postcode resolves to its metro. Every row is specific to one country.

Company groups and ownership. Company groups (parent_company_id, ticker) use current ownership for every period (meta.ownership_basis: current). A brand acquired last year is counted in its current parent's history.

IDs, not plain text. Statistics take IDs. Resolve names to IDs first with lookup (company, ticker, place, city, postcode, job family, sub-job family) or send occupation codes (occupation_code). Plain-text filters (title, company, location, job_family) are not available at launch and answer 501 with a retry_with lookup link.

Request size. A request answers up to 1,000 rows and 200 filter combinations inline; larger requests answer 501 job_required - narrow the filters or periods. Asynchronous jobs come later.

Provenance and reproducibility. Every response carries meta.provenance (the data release and its last complete week) and a ready-made meta.citation. Statistics come from the live weekly release; each response names it.

Notes

• Add compare=previous or compare=12_month for the change; change_null_reason explains a null change.
• Use one company filter and one occupation filter per call.
• Occupation codes: send occupation_code=isco_08:2512 (also soc_2018, soc_2010, onet_soc, esco) or soc_id; you get one row set per SOC 2018 detailed occupation the code maps to, each with matched_from. A partial match covers only part of the SOC occupation - say so. Never add SOC rows together for pay. SOC occupations are by geography and job level only.
• parent_company_id or ticker combines all brands; add split=brand for one row per brand.
• Weekly figures (interval=week) are served for occupations, single companies (also brand by brand with split=brand) and industries on their own; for a parent company or ticker, a company or industry combined with an occupation, or industry benchmarks, use month, quarter or year (weekly returns 501).

How to word results

• Cite GWIX using meta.citation.
• Say "advertised pay" or "pay in job ads", never "salary paid" or "what X pays".
• State the currency of every pay figure (the row's currency).
• Say "ads first posted", not "jobs" or "hires" or "openings filled".
• Report suppressed percentiles as "not enough ads stating pay to report", not as zero.
• Report zeros with covered as "no ads observed in GWIX sources", not "no jobs exist".
• State the level actually used (e.g. metro, 4-digit NAICS) from meta.
• For company groups, say figures use current ownership.
• Never: present figures as official statistics or as an employer's actual pay.
• Never: name a data vendor; name datasets as they appear in meta.provenance.

When it doesn't work

Next steps

get_pay · lookup

Example response

{
  "rows": [
    {
      "period_label": "2026-Q3",
      "period_start": "2026-06-29",
      "period_end": "2026-09-27",
      "country": "US",
      "company": {
        "id": "cmp_acme_retail",
        "name": "Acme Retail"
      },
      "job_family": {
        "id": "jfm_nursing",
        "name": "Nursing"
      },
      "coverage_status": "covered",
      "new_postings": 1284,
      "prior_new_postings": 1102,
      "change_pct": 16.5
    }
  ],
  "meta": {
    "request_id": "gwx_req_8f3k2m",
    "resolved": [],
    "period_definition": "13-week quarters of whole Monday\u2013Sunday weeks",
    "zero_rows_omitted": 0,
    "provenance": {
      "datasets": [
        {
          "id": "us-postings-core",
          "last_complete_week": "2026-10-25"
        }
      ],
      "data_release": "2026-W43",
      "taxonomy_version": "utb-1.0",
      "computed_at": "2026-10-28T14:02:09Z"
    },
    "citation": {
      "text": "GWIX ad volume, Acme Retail, Nursing, US, 2026-Q3, release 2026-W43, retrieved 28 Oct 2026 (gwx_req_8f3k2m)",
      "url": "https://api.gwix.ai/v1/requests/gwx_req_8f3k2m"
    }
  },
  "paging": {
    "next_cursor": null
  }
}