---
title: "Search Hiring Aggregators"
method: POST
path: "/hiring-signals/aggregators"
tags: ["Signals"]
---

# Search Hiring Aggregators

`POST /hiring-signals/aggregators`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/hiring-signals/aggregators`
- Auth: HTTP bearer

What `exclude_aggregators` suppressed.

The audit trail for the suppression: a job board is not a company that is
hiring, but a caller should be able to see what was dropped rather than
take it on trust.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- JobSearchRequest: One request shape for every Hiring Signals tab. The app uses a single command for all of them deliberately - the form is flat, and each handler needs both the base filters and the persona half. Splitting them here would just add a layer the routes flatten back out.
  - `keywords` string[], required: Job-title keywords. OR semantics - any match counts.
  - `window_days` integer: How far back to look for postings.
  - `location_contains` string, nullable: Free-text token matched case-insensitively against the job location.
  - `persona_seniority` string[], nullable: Decision-maker seniority filter.
  - `persona_department` string[], nullable: Decision-maker department filter.
  - `persona_title_contains` string, nullable: Decision-maker title substring filter.
  - `contacts_per_company` integer
  - `exclude_aggregators` boolean: Drop postings from job-board aggregators. On by default because an aggregator is not a company that is hiring - it is a company that lists other people's jobs. `/jobs/search/aggregators` returns exactly what this suppressed, so a caller can audit it.
  - `per_company_cap` integer: Max postings counted per company.
  - `parent_linkedin_company_id` integer, nullable: Scope to one parent company and its subsidiaries. Omit to search everywhere.
  - `limit` integer: Page size. Capped at 200 to bound the ClickHouse cost.
  - `offset` integer
  - `include_recruiters` boolean: Run the recruiter aggregation and enrichment hop. Set false to skip two round-trips when only Companies and Decision-makers are needed.
  - `recruiter_limit` integer: Recruiter paging, INDEPENDENT of `limit`/`offset`: one recruiter can serve many companies, so the two counts diverge and a caller can page one tab without touching the other.
  - `recruiter_offset` integer

## Response `200`

Successful Response

- ApiResponseJobSearchResponse
  - `data` JobSearchResponse, required: A page of Hiring Signals results. Rows stay open dicts: each tab (jobs, companies, decision-makers, recruiters, aggregators) returns a different shape assembled from ClickHouse plus OpenSearch, and the columns move as enrichment improves.
    - `results` object[]
    - `total` integer
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/2e7cfa0ca921?raw)