@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/signals.md

@@ -0,0 +1,2526 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.signals`: Signals
+
+56 operations (23 read, 3 destructive, 29 billable, 1 external).
+
+No hand-written client covers this area. Call it through `g8.api.signals.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [signals.d.ts](signals.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`addEngagersToList`](#op-addengagerstolist) | `POST /api/v1/social-listeners/posts/{post_id}/engagements/add-to-list` | billable | `intent:run` | Add Engagers To List |
+| [`addPostAuthorToSequence`](#op-addpostauthortosequence) | `POST /api/v1/social-listeners/posts/{post_id}/add-to-sequence` | external | `intent:run` | Add Post Author To Sequence |
+| [`autoSeedAllListeners`](#op-autoseedalllisteners) | `POST /api/v1/social-listeners/auto-seed/all` | billable | `intent:run` | Auto Seed All Listeners |
+| [`autoSeedBrandListener`](#op-autoseedbrandlistener) | `POST /api/v1/social-listeners/auto-seed/brand` | billable | `intent:run` | Auto Seed Brand Listener |
+| [`autoSeedCompetitorListeners`](#op-autoseedcompetitorlisteners) | `POST /api/v1/social-listeners/auto-seed/competitors` | billable | `intent:run` | Auto Seed Competitor Listeners |
+| [`autoSeedEngagementListeners`](#op-autoseedengagementlisteners) | `POST /api/v1/social-listeners/auto-seed/engagement` | billable | `intent:run` | Auto Seed Engagement Listeners |
+| [`autoSeedKeywordListeners`](#op-autoseedkeywordlisteners) | `POST /api/v1/social-listeners/auto-seed/keywords` | billable | `intent:run` | Auto Seed Keyword Listeners |
+| [`bulkCreateListenersFromList`](#op-bulkcreatelistenersfromlist) | `POST /api/v1/social-listeners/bulk-from-list` | billable | `intent:run` | Bulk Create Listeners From List |
+| [`connectXCredentials`](#op-connectxcredentials) | `POST /api/v1/social-listeners/integrations/x` | billable | `intent:run` | Connect X Credentials |
+| [`createListener`](#op-createlistener) | `POST /api/v1/social-listeners` | billable | `intent:run` | Create Listener |
+| [`deleteKeywordUrl`](#op-deletekeywordurl) | `DELETE /api/v1/intent/keyword-urls/{url_id}` | destructive | `intent:delete` | Delete Keyword Url |
+| [`deleteListener`](#op-deletelistener) | `DELETE /api/v1/social-listeners/{listener_id}` | destructive | `intent:delete` | Delete Listener |
+| [`disconnectXCredentials`](#op-disconnectxcredentials) | `DELETE /api/v1/social-listeners/integrations/x` | destructive | `intent:delete` | Disconnect X Credentials |
+| [`generateListenerQuery`](#op-generatelistenerquery) | `POST /api/v1/social-listeners/queries/generate` | billable | `intent:run` | Generate Listener Query |
+| [`getAbmCompanyPersonas`](#op-getabmcompanypersonas) | `GET /api/v1/intent/abm/companies/{company_id}/personas` | read | `intent:read` | Get Abm Company Personas |
+| [`getAutoSeedStatus`](#op-getautoseedstatus) | `GET /api/v1/social-listeners/auto-seed-status` | read | `intent:read` | Get Auto Seed Status |
+| [`getCompanyJobCounts`](#op-getcompanyjobcounts) | `POST /api/v1/hiring-signals/companies/job-counts` | billable | `intent:run` | Get Company Job Counts |
+| [`getHiringJobDetails`](#op-gethiringjobdetails) | `GET /api/v1/hiring-signals/jobs/{job_id}` | read | `intent:read` | Get Hiring Job Details |
+| [`getJobResolutionStatus`](#op-getjobresolutionstatus) | `GET /api/v1/intent/keywords/{keyword_id}/job-resolution` | read | `intent:read` | Get Job Resolution Status |
+| [`getKeywordSyncConfig`](#op-getkeywordsyncconfig) | `GET /api/v1/intent/keywords/{keyword_id}/sync-config` | read | `intent:read` | Get Keyword Sync Config |
+| [`getListener`](#op-getlistener) | `GET /api/v1/social-listeners/{listener_id}` | read | `intent:read` | Get Listener |
+| [`getSocialSettings`](#op-getsocialsettings) | `GET /api/v1/social-listeners/settings` | read | `intent:read` | Get Social Settings |
+| [`getSocialStats`](#op-getsocialstats) | `GET /api/v1/social-listeners/stats` | read | `intent:read` | Get Social Stats |
+| [`getXEffectiveMode`](#op-getxeffectivemode) | `GET /api/v1/social-listeners/integrations/x/mode` | read | `intent:read` | Get X Effective Mode |
+| [`getXIntegration`](#op-getxintegration) | `GET /api/v1/social-listeners/integrations/x` | read | `intent:read` | Get X Integration |
+| [`listAbmCompanies`](#op-listabmcompanies) | `GET /api/v1/intent/abm/companies` | read | `intent:read` | List Abm Companies |
+| [`listCompanyHiringJobs`](#op-listcompanyhiringjobs) | `GET /api/v1/hiring-signals/companies/{linkedin_company_id}/jobs` | read | `intent:read` | List Company Hiring Jobs |
+| [`listCompanyLinkedinPosts`](#op-listcompanylinkedinposts) | `GET /api/v1/hiring-signals/companies/{linkedin_company_id}/linkedin-posts` | read | `intent:read` | List Company Linkedin Posts |
+| [`listJobChangeSignals`](#op-listjobchangesignals) | `GET /api/v1/hiring-signals/job-changes` | read | `intent:read` | List Job Change Signals |
+| [`listListeners`](#op-listlisteners) | `GET /api/v1/social-listeners` | read | `intent:read` | List Listeners |
+| [`listPostsByContact`](#op-listpostsbycontact) | `GET /api/v1/social-listeners/posts/by-contact/{contact_id}` | read | `intent:read` | List Posts By Contact |
+| [`listSourceLists`](#op-listsourcelists) | `GET /api/v1/social-listeners/source-lists` | read | `intent:read` | List Source Lists |
+| [`listTopEngagedAccounts`](#op-listtopengagedaccounts) | `GET /api/v1/social-listeners/engagements/top-accounts` | read | `intent:read` | List Top Engaged Accounts |
+| [`markPost`](#op-markpost) | `POST /api/v1/social-listeners/posts/{post_id}/mark` | billable | `intent:run` | Mark Post |
+| [`matchJobChangeSignals`](#op-matchjobchangesignals) | `POST /api/v1/hiring-signals/job-changes/match` | billable | `intent:run` | Match Job Change Signals |
+| [`previewKeywordUrls`](#op-previewkeywordurls) | `POST /api/v1/intent/keywords/preview` | read | `intent:read` | Preview Keyword Urls |
+| [`previewListenerCost`](#op-previewlistenercost) | `POST /api/v1/social-listeners/preview-cost` | read | `intent:read` | Preview Listener Cost |
+| [`proposeHiringKeywords`](#op-proposehiringkeywords) | `POST /api/v1/intent/keywords/auto-seed-proposals` | billable | `intent:run` | Propose Hiring Keywords |
+| [`resolveHiringCompanyIds`](#op-resolvehiringcompanyids) | `POST /api/v1/hiring-signals/companies/resolve-ids` | billable | `intent:run` | Resolve Hiring Company Ids |
+| [`resolveJobsForKeyword`](#op-resolvejobsforkeyword) | `POST /api/v1/intent/keywords/{keyword_id}/job-resolution` | billable | `intent:run` | Resolve Jobs For Keyword |
+| [`rollupAbmCompanies`](#op-rollupabmcompanies) | `POST /api/v1/intent/abm/rollup` | read | `intent:read` | Rollup Abm Companies |
+| [`saveIntentToContactMetadata`](#op-saveintenttocontactmetadata) | `POST /api/v1/intent/contacts/metadata` | billable | `intent:run` | Save Intent To Contact Metadata |
+| [`saveKeywordSyncConfig`](#op-savekeywordsyncconfig) | `PATCH /api/v1/intent/keywords/{keyword_id}/sync-config` | billable | `intent:run` | Save Keyword Sync Config |
+| [`savePostAuthorAsContact`](#op-savepostauthorascontact) | `POST /api/v1/social-listeners/posts/{post_id}/save-contact` | billable | `intent:run` | Save Post Author As Contact |
+| [`searchHiringAggregators`](#op-searchhiringaggregators) | `POST /api/v1/hiring-signals/aggregators` | billable | `intent:run` | Search Hiring Aggregators |
+| [`searchHiringCompanies`](#op-searchhiringcompanies) | `POST /api/v1/hiring-signals/companies` | billable | `intent:run` | Search Hiring Companies |
+| [`searchHiringDecisionMakers`](#op-searchhiringdecisionmakers) | `POST /api/v1/hiring-signals/decision-makers` | billable | `intent:run` | Search Hiring Decision Makers |
+| [`searchHiringJobs`](#op-searchhiringjobs) | `POST /api/v1/hiring-signals/jobs` | billable | `intent:run` | Search Hiring Jobs |
+| [`searchHiringRecruiters`](#op-searchhiringrecruiters) | `POST /api/v1/hiring-signals/recruiters` | billable | `intent:run` | Search Hiring Recruiters |
+| [`searchMatchedPosts`](#op-searchmatchedposts) | `POST /api/v1/social-listeners/posts/search` | read | `intent:read` | Search Matched Posts |
+| [`searchPostEngagements`](#op-searchpostengagements) | `POST /api/v1/social-listeners/posts/{post_id}/engagements/search` | read | `intent:read` | Search Post Engagements |
+| [`testXCredentials`](#op-testxcredentials) | `POST /api/v1/social-listeners/integrations/x/test` | billable | `intent:run` | Test X Credentials |
+| [`triggerKeywordSync`](#op-triggerkeywordsync) | `POST /api/v1/intent/keywords/{keyword_id}/sync` | billable | `intent:run` | Trigger Keyword Sync |
+| [`updateHiringKeyword`](#op-updatehiringkeyword) | `PATCH /api/v1/intent/keywords/{keyword_id}` | billable | `intent:run` | Update Hiring Keyword |
+| [`updateListener`](#op-updatelistener) | `PATCH /api/v1/social-listeners/{listener_id}` | billable | `intent:run` | Update Listener |
+| [`updateSocialSettings`](#op-updatesocialsettings) | `PATCH /api/v1/social-listeners/settings` | billable | `intent:run` | Update Social Settings |
+
+---
+
+<a id="op-addengagerstolist"></a>
+
+### `g8.api.signals.addEngagersToList(input)`
+
+**Add Engagers To List**
+
+- HTTP: `POST /api/v1/social-listeners/posts/{post_id}/engagements/add-to-list`
+- operationId: `add_engagers_to_list_social_listeners_posts__post_id__engagements_add_to_list_post` (also callable as `g8.api.call("add_engagers_to_list_social_listeners_posts__post_id__engagements_add_to_list_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Turn the people who engaged with a post into a graph8 list.
+
+CREATES CONTACTS. Engagers with no matching graph8 contact are created as
+stubs, so this grows the contact database as well as the list.
+
+Supply `audience_id` for an existing list or `audience_name` to create one.
+The app does not gate this on `signals:write`; this surface does, because
+creating contacts from a public post is a write by any reading and the
+app's omission looks like an oversight rather than a decision.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's platform-native id. |
+| `body` | `AddEngagersToListRequest` | yes | Request body; fields below. |
+
+Body fields (`AddEngagersToListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience_id` | `string \| null` | no | An existing graph8 list. |
+| `body.audience_name` | `string \| null` | no | Create a new graph8 list with this name. max length 255 |
+| `body.engagement_type` | `"comment" \| "reaction" \| null` | no | Only commenters, or only reactors. Omit for both. |
+| `body.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"` | no | default `"linkedin"` |
+| `body.post_external_id` | `string \| null` | no | Optional echo of the path id. The PATH value is authoritative. |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.addEngagersToList({ path: { post_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-addpostauthortosequence"></a>
+
+### `g8.api.signals.addPostAuthorToSequence(input)`
+
+**Add Post Author To Sequence**
+
+- HTTP: `POST /api/v1/social-listeners/posts/{post_id}/add-to-sequence`
+- operationId: `add_post_author_to_sequence_social_listeners_posts__post_id__add_to_sequence_post` (also callable as `g8.api.call("add_post_author_to_sequence_social_listeners_posts__post_id__add_to_sequence_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `intent:run`
+
+Enrol a post's author into a sequence.
+
+202, NOT 200: this resolves the author to a contact and publishes an
+enrolment REQUEST. The sequencer consumes it afterwards, and it is that
+consumer - not this call - that starts sending to a real person. A 202 here
+does not mean the person is enrolled, and it does not mean they are not
+about to be.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's platform-native id. |
+| `body` | `AddPostToSequenceRequest` | yes | Request body; fields below. |
+
+Body fields (`AddPostToSequenceRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.sequence_id` | `string` | yes |  |
+| `body.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"` | no | default `"x"` |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.signals.addPostAuthorToSequence({ path: { post_id: "id" }, body: { sequence_id: "id" } });
+```
+
+---
+
+<a id="op-autoseedalllisteners"></a>
+
+### `g8.api.signals.autoSeedAllListeners(input?)`
+
+**Auto Seed All Listeners**
+
+- HTTP: `POST /api/v1/social-listeners/auto-seed/all`
+- operationId: `auto_seed_all_listeners_social_listeners_auto_seed_all_post` (also callable as `g8.api.call("auto_seed_all_listeners_social_listeners_auto_seed_all_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Run every auto-seed in one go. ASYNCHRONOUS, AND IT SPENDS CREDITS.
+
+202 is returned BEFORE any seeding happens. The brand, competitor and
+engagement stages each make their own charged LLM call afterwards, in a
+background task - so up to three charges land after this response, and a
+caller that only reads the response body will not see any of them. Poll
+`GET /social-listeners/auto-seed-status` with the returned `job_id`.
+
+Each stage fails independently: a partial result is normal and is not an
+error.
+
+409 if a run is already in flight.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SeedChannelsRequest \| null` | no | Request body; fields below. |
+
+Body fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.channels` | `Array<"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"> \| null` | no |  |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.autoSeedAllListeners();
+```
+
+---
+
+<a id="op-autoseedbrandlistener"></a>
+
+### `g8.api.signals.autoSeedBrandListener(input?)`
+
+**Auto Seed Brand Listener**
+
+- HTTP: `POST /api/v1/social-listeners/auto-seed/brand`
+- operationId: `auto_seed_brand_listener_social_listeners_auto_seed_brand_post` (also callable as `g8.api.call("auto_seed_brand_listener_social_listeners_auto_seed_brand_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Create a brand listener from the org's brand documents.
+
+SPENDS CREDITS - an LLM call extracts the brand and product names. The
+charge happens BEFORE the listeners are inserted, so a failure after
+extraction still costs. 400 if the org has no brand brief to read.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.autoSeedBrandListener();
+```
+
+---
+
+<a id="op-autoseedcompetitorlisteners"></a>
+
+### `g8.api.signals.autoSeedCompetitorListeners(input?)`
+
+**Auto Seed Competitor Listeners**
+
+- HTTP: `POST /api/v1/social-listeners/auto-seed/competitors`
+- operationId: `auto_seed_competitor_listeners_social_listeners_auto_seed_competitors_post` (also callable as `g8.api.call("auto_seed_competitor_listeners_social_listeners_auto_seed_competitors_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Create competitor listeners from the org's brand documents.
+
+SPENDS CREDITS - an LLM call extracts the competitor names, charged before
+the listeners are inserted.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.autoSeedCompetitorListeners();
+```
+
+---
+
+<a id="op-autoseedengagementlisteners"></a>
+
+### `g8.api.signals.autoSeedEngagementListeners(input?)`
+
+**Auto Seed Engagement Listeners**
+
+- HTTP: `POST /api/v1/social-listeners/auto-seed/engagement`
+- operationId: `auto_seed_engagement_listeners_social_listeners_auto_seed_engagement_post` (also callable as `g8.api.call("auto_seed_engagement_listeners_social_listeners_auto_seed_engagement_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Create ICP-shaped engagement listeners.
+
+SPENDS CREDITS - one LLM call produces two or three query buckets, charged
+ONCE regardless of how many channels the buckets fan out to.
+
+Omit the body entirely to take the app's own default channel set (X alone)
+rather than this contract freezing a copy of it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SeedChannelsRequest \| null` | no | Request body; fields below. |
+
+Body fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.channels` | `Array<"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"> \| null` | no |  |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.autoSeedEngagementListeners();
+```
+
+---
+
+<a id="op-autoseedkeywordlisteners"></a>
+
+### `g8.api.signals.autoSeedKeywordListeners(input?)`
+
+**Auto Seed Keyword Listeners**
+
+- HTTP: `POST /api/v1/social-listeners/auto-seed/keywords`
+- operationId: `auto_seed_keyword_listeners_social_listeners_auto_seed_keywords_post` (also callable as `g8.api.call("auto_seed_keyword_listeners_social_listeners_auto_seed_keywords_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Create keyword listeners from the org's existing keyword intelligence.
+
+The ONLY auto-seed that charges nothing: it reads keywords that were
+already gathered rather than asking an LLM for new ones. Start here.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.autoSeedKeywordListeners();
+```
+
+---
+
+<a id="op-bulkcreatelistenersfromlist"></a>
+
+### `g8.api.signals.bulkCreateListenersFromList(input)`
+
+**Bulk Create Listeners From List**
+
+- HTTP: `POST /api/v1/social-listeners/bulk-from-list`
+- operationId: `bulk_create_listeners_from_list_social_listeners_bulk_from_list_post` (also callable as `g8.api.call("bulk_create_listeners_from_list_social_listeners_bulk_from_list_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+One `user` listener per social profile on a graph8 list.
+
+No platform lookup happens here - handles are resolved lazily by the
+polling worker on first poll, so this does not burn one API call per row at
+creation time.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `BulkCreateFromListRequest` | yes | Request body; fields below. |
+
+Body fields (`BulkCreateFromListRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.list_id` | `integer` | yes | The graph8 audience to read profiles from. |
+| `body.listener_type` | `"user"` | no | Only `user` listeners can be bulk-created from a list. default `"user"` |
+| `body.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"` | no | default `"x"` |
+| `body.platforms` | `Array<"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"> \| null` | no | Create one listener per platform. Overrides `platform`. |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.bulkCreateListenersFromList({ body: { list_id: 123 } });
+```
+
+---
+
+<a id="op-connectxcredentials"></a>
+
+### `g8.api.signals.connectXCredentials(input)`
+
+**Connect X Credentials**
+
+- HTTP: `POST /api/v1/social-listeners/integrations/x`
+- operationId: `connect_x_credentials_social_listeners_integrations_x_post` (also callable as `g8.api.call("connect_x_credentials_social_listeners_integrations_x_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Store the org's own X developer credentials.
+
+WRITE-ONLY. The key, the secret and the bearer token derived from them are
+encrypted at rest and are never returned - not by this route, and not by
+any other on this surface.
+
+With credentials stored the org pays X directly and is not bounded by
+graph8's shared quota. Test them first with
+`POST /social-listeners/integrations/x/test`, which validates without
+storing anything.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `XApiCredentialsRequest` | yes | Request body; fields below. |
+
+Body fields (`XApiCredentialsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.api_key` | `string` | yes | X Developer App API key (consumer key). min length 1 |
+| `body.api_secret` | `string` | yes | X Developer App API secret. min length 1 |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.connectXCredentials({ body: { api_key: "example", api_secret: "example" } });
+```
+
+---
+
+<a id="op-createlistener"></a>
+
+### `g8.api.signals.createListener(input)`
+
+**Create Listener**
+
+- HTTP: `POST /api/v1/social-listeners`
+- operationId: `create_listener_social_listeners_post` (also callable as `g8.api.call("create_listener_social_listeners_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Start watching something.
+
+THIS CAN SPEND CREDITS: a `brand` listener with no `query` has one built by
+an LLM call, which is charged. Supply `query`, or call
+`POST /social-listeners/queries/generate` first, to see what you are
+committing to.
+
+A `user` listener additionally resolves `target_handle` against the
+platform, which consumes the org's X API quota.
+
+Set `monthly_credit_cap` unless you have set an org-wide one - it is the
+only per-listener bound on what this costs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateListenerRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateListenerRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.listener_type` | `"brand" \| "competitor" \| "keyword" \| "engagement" \| "user"` | yes | `brand` and `competitor` watch a named entity, `keyword` watches a query, `engagement` watches an ICP-shaped bucket, `user` watches one account's posts. |
+| `body.name` | `string` | yes | min length 1 |
+| `body.filters` | `Record<string, unknown>` | no |  |
+| `body.force_rebuild_brand` | `boolean` | no | Rebuild a brand query even though one exists. Spends a credit to do it. default `false` |
+| `body.monthly_credit_cap` | `integer \| null` | no | Per-listener ceiling on credits. The one field that BOUNDS what this costs. min 0 |
+| `body.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"` | no | default `"x"` |
+| `body.poll_interval_sec` | `integer \| null` | no | How often the worker polls. Shorter means more matches AND more spend. min 60 |
+| `body.query` | `string \| null` | no | Platform-native search query. OMITTING this on a `brand` listener makes the app build one with an LLM call, which SPENDS CREDITS. Supply a query, or call `POST /social-listeners/queries/generate` first if you want to see it before committing. |
+| `body.target_handle` | `string \| null` | no | Required for a `user` listener: the account to watch. |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.createListener({ body: { listener_type: "brand", name: "Example" } });
+```
+
+---
+
+<a id="op-deletekeywordurl"></a>
+
+### `g8.api.signals.deleteKeywordUrl(input)`
+
+**Delete Keyword Url**
+
+- HTTP: `DELETE /api/v1/intent/keyword-urls/{url_id}`
+- operationId: `delete_keyword_url_intent_keyword_urls__url_id__delete` (also callable as `g8.api.call("delete_keyword_url_intent_keyword_urls__url_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `intent:delete`
+
+Remove one URL from a keyword's matched set (soft delete).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.url_id` | `string (uuid)` | yes | The keyword URL's id. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.signals.deleteKeywordUrl({ path: { url_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-deletelistener"></a>
+
+### `g8.api.signals.deleteListener(input)`
+
+**Delete Listener**
+
+- HTTP: `DELETE /api/v1/social-listeners/{listener_id}`
+- operationId: `delete_listener_social_listeners__listener_id__delete` (also callable as `g8.api.call("delete_listener_social_listeners__listener_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `intent:delete`
+
+Delete a listener.
+
+Gated on `signals:delete` specifically, not on `signals:write` - the app
+separates them, and so does this. To stop the spend without losing the
+matched posts, PATCH `is_active: false` instead.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.listener_id` | `string (uuid)` | yes | The listener's id. |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.signals.deleteListener({ path: { listener_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-disconnectxcredentials"></a>
+
+### `g8.api.signals.disconnectXCredentials(input?)`
+
+**Disconnect X Credentials**
+
+- HTTP: `DELETE /api/v1/social-listeners/integrations/x`
+- operationId: `disconnect_x_credentials_social_listeners_integrations_x_delete` (also callable as `g8.api.call("disconnect_x_credentials_social_listeners_integrations_x_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `intent:delete`
+
+Remove the org's own X credentials.
+
+THIS PAUSES LISTENERS. Every active X listener is paused; if graph8's
+shared mode is available they are immediately reactivated under it, with an
+alert per listener. If it is not, they stay paused and stop matching.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.signals.disconnectXCredentials();
+```
+
+---
+
+<a id="op-generatelistenerquery"></a>
+
+### `g8.api.signals.generateListenerQuery(input)`
+
+**Generate Listener Query**
+
+- HTTP: `POST /api/v1/social-listeners/queries/generate`
+- operationId: `generate_listener_query_social_listeners_queries_generate_post` (also callable as `g8.api.call("generate_listener_query_social_listeners_queries_generate_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Turn a plain-English description into a platform-native query.
+
+THIS SPENDS CREDITS - it is an LLM call. It returns the query rather than
+creating a listener, so the query can be read, edited and reused across
+several listeners for the price of one generation.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `GenerateQueryRequest` | yes | Request body; fields below. |
+
+Body fields (`GenerateQueryRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.description` | `string` | yes | min length 1, max length 1000 |
+| `body.listener_type` | `"brand" \| "competitor" \| "keyword" \| "engagement" \| "user"` | yes |  |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.generateListenerQuery({ body: { description: "example", listener_type: "brand" } });
+```
+
+---
+
+<a id="op-getabmcompanypersonas"></a>
+
+### `g8.api.signals.getAbmCompanyPersonas(input)`
+
+**Get Abm Company Personas**
+
+- HTTP: `GET /api/v1/intent/abm/companies/{company_id}/personas`
+- operationId: `get_abm_company_personas_intent_abm_companies__company_id__personas_get` (also callable as `g8.api.call("get_abm_company_personas_intent_abm_companies__company_id__personas_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Who to contact at one account showing intent: its buying committee, persona by persona.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.company_id` | `integer` | yes | Company id. |
+| `query.days` | `integer` | no | Look-back window in days. default `30` |
+| `query.export_mode` | `"signals_only" \| "icp_plus_signals" \| "all_icp_personas"` | no | The same three modes as a keyword's sync config, so this previews what a sync exports. default `"icp_plus_signals"` |
+| `query.icp_id` | `string (uuid) \| null` | no | Score against this ICP. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getAbmCompanyPersonas({ path: { company_id: 1 } });
+```
+
+---
+
+<a id="op-getautoseedstatus"></a>
+
+### `g8.api.signals.getAutoSeedStatus(input?)`
+
+**Get Auto Seed Status**
+
+- HTTP: `GET /api/v1/social-listeners/auto-seed-status`
+- operationId: `get_auto_seed_status_social_listeners_auto_seed_status_get` (also callable as `g8.api.call("get_auto_seed_status_social_listeners_auto_seed_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+How the asynchronous `/auto-seed/all` run is going.
+
+The only way to see what that call did: it answers 202 before any of the
+seeding, or any of the credit spend, has happened.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.job_id` | `string \| null` | no | A job id from `/auto-seed/all`. Omit for the most recent run. |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getAutoSeedStatus();
+```
+
+---
+
+<a id="op-getcompanyjobcounts"></a>
+
+### `g8.api.signals.getCompanyJobCounts(input)`
+
+**Get Company Job Counts**
+
+- HTTP: `POST /api/v1/hiring-signals/companies/job-counts`
+- operationId: `get_company_job_counts_hiring_signals_companies_job_counts_post` (also callable as `g8.api.call("get_company_job_counts_hiring_signals_companies_job_counts_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Active-job counts for a page of companies, in one call.
+
+Capped at 1000 lcids: this is for decorating a grid page, not scanning a
+corpus.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CompanyJobCountsRequest` | yes | Request body; fields below. |
+
+Body fields (`CompanyJobCountsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.linkedin_company_ids` | `Array<integer>` | no | LinkedIn company ids (lcids). Capped at 1000 - one grid page, not a corpus scan. max items 1000 |
+| `body.window_days` | `integer` | no | default `60`, min 1, max 365 |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.getCompanyJobCounts({ body: {} });
+```
+
+---
+
+<a id="op-gethiringjobdetails"></a>
+
+### `g8.api.signals.getHiringJobDetails(input)`
+
+**Get Hiring Job Details**
+
+- HTTP: `GET /api/v1/hiring-signals/jobs/{job_id}`
+- operationId: `get_hiring_job_details_hiring_signals_jobs__job_id__get` (also callable as `g8.api.call("get_hiring_job_details_hiring_signals_jobs__job_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+One posting, with its company, its recruiter and the company's other jobs.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.job_id` | `integer` | yes | Job id. |
+
+**Returns** `ApiResponse_JobDetails_`: the envelope `{ data: JobDetails, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobDetails` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `company_name` | `string \| null` | no |  |
+| `job_id` | `integer \| null` | no |  |
+| `job_location` | `string \| null` | no |  |
+| `linkedin_company_id` | `integer \| null` | no |  |
+| `posted_at` | `string (date-time) \| null` | no |  |
+| `title` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getHiringJobDetails({ path: { job_id: 123 } });
+```
+
+---
+
+<a id="op-getjobresolutionstatus"></a>
+
+### `g8.api.signals.getJobResolutionStatus(input)`
+
+**Get Job Resolution Status**
+
+- HTTP: `GET /api/v1/intent/keywords/{keyword_id}/job-resolution`
+- operationId: `get_job_resolution_status_intent_keywords__keyword_id__job_resolution_get` (also callable as `g8.api.call("get_job_resolution_status_intent_keywords__keyword_id__job_resolution_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+When the resolver last ran for this keyword, and what it emitted. Empty if it never has.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes | The keyword's id. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getJobResolutionStatus({ path: { keyword_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getkeywordsyncconfig"></a>
+
+### `g8.api.signals.getKeywordSyncConfig(input)`
+
+**Get Keyword Sync Config**
+
+- HTTP: `GET /api/v1/intent/keywords/{keyword_id}/sync-config`
+- operationId: `get_keyword_sync_config_intent_keywords__keyword_id__sync_config_get` (also callable as `g8.api.call("get_keyword_sync_config_intent_keywords__keyword_id__sync_config_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Which list this keyword feeds, and whether on a schedule. Defaults when never configured.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes | The keyword's id. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getKeywordSyncConfig({ path: { keyword_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getlistener"></a>
+
+### `g8.api.signals.getListener(input)`
+
+**Get Listener**
+
+- HTTP: `GET /api/v1/social-listeners/{listener_id}`
+- operationId: `get_listener_social_listeners__listener_id__get` (also callable as `g8.api.call("get_listener_social_listeners__listener_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+One listener, with its match count and running credit burn.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.listener_id` | `string (uuid)` | yes | The listener's id. |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getListener({ path: { listener_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getsocialsettings"></a>
+
+### `g8.api.signals.getSocialSettings(input?)`
+
+**Get Social Settings**
+
+- HTTP: `GET /api/v1/social-listeners/settings`
+- operationId: `get_social_settings_social_listeners_settings_get` (also callable as `g8.api.call("get_social_settings_social_listeners_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Org-wide social listening settings, including every spend ceiling.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getSocialSettings();
+```
+
+---
+
+<a id="op-getsocialstats"></a>
+
+### `g8.api.signals.getSocialStats(input?)`
+
+**Get Social Stats**
+
+- HTTP: `GET /api/v1/social-listeners/stats`
+- operationId: `get_social_stats_social_listeners_stats_get` (also callable as `g8.api.call("get_social_stats_social_listeners_stats_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Match counts, listener counts and platform spend to date.
+
+The number to watch against `monthly_credit_cap`.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getSocialStats();
+```
+
+---
+
+<a id="op-getxeffectivemode"></a>
+
+### `g8.api.signals.getXEffectiveMode(input?)`
+
+**Get X Effective Mode**
+
+- HTTP: `GET /api/v1/social-listeners/integrations/x/mode`
+- operationId: `get_x_effective_mode_social_listeners_integrations_x_mode_get` (also callable as `g8.api.call("get_x_effective_mode_social_listeners_integrations_x_mode_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Which X credentials this org is ACTUALLY polling with, and how much of
+the shared allowance is left.
+
+Not the same question as `GET /social-listeners/integrations/x`: an org can
+have credentials stored and still be on shared mode, and an org on shared
+mode is competing for a quota it does not control. This is the number to
+read when listeners stop matching.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getXEffectiveMode();
+```
+
+---
+
+<a id="op-getxintegration"></a>
+
+### `g8.api.signals.getXIntegration(input?)`
+
+**Get X Integration**
+
+- HTTP: `GET /api/v1/social-listeners/integrations/x`
+- operationId: `get_x_integration_social_listeners_integrations_x_get` (also callable as `g8.api.call("get_x_integration_social_listeners_integrations_x_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Whether the org has its own X credentials stored, and since when.
+
+Reports that a connection exists. It does not report what it is - see
+`POST /social-listeners/integrations/x`.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.getXIntegration();
+```
+
+---
+
+<a id="op-listabmcompanies"></a>
+
+### `g8.api.signals.listAbmCompanies(input?)`
+
+**List Abm Companies**
+
+- HTTP: `GET /api/v1/intent/abm/companies`
+- operationId: `list_abm_companies_intent_abm_companies_get` (also callable as `g8.api.call("list_abm_companies_intent_abm_companies_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Accounts showing intent, one scored row per company, with buying-committee coverage.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Look-back window in days. default `30` |
+| `query.keyword_ids` | `string \| null` | no | Comma-separated keyword ids to restrict to. |
+| `query.icp_id` | `string (uuid) \| null` | no | Score against this ICP. |
+| `query.page` | `integer` | no | default `1` |
+| `query.limit` | `integer` | no | default `50` |
+| `query.agFilterModel` | `string \| null` | no | Grid filter model as JSON, passed through unchanged. |
+| `query.agSortModel` | `string \| null` | no | Grid sort model as JSON (`colId`, `sort`). |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.listAbmCompanies();
+```
+
+---
+
+<a id="op-listcompanyhiringjobs"></a>
+
+### `g8.api.signals.listCompanyHiringJobs(input)`
+
+**List Company Hiring Jobs**
+
+- HTTP: `GET /api/v1/hiring-signals/companies/{linkedin_company_id}/jobs`
+- operationId: `list_company_hiring_jobs_hiring_signals_companies__linkedin_company_id__jobs_get` (also callable as `g8.api.call("list_company_hiring_jobs_hiring_signals_companies__linkedin_company_id__jobs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Recent postings at one company.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.linkedin_company_id` | `integer` | yes | LinkedIn company id (lcid). |
+| `query.limit` | `integer` | no | default `50` |
+| `query.window_days` | `integer` | no | default `60` |
+| `query.include_subsidiaries` | `boolean` | no | Expand the lcid to its subsidiaries, so a parent company's view surfaces postings made under a child lcid. On by default because the parent is usually who the customer is selling to. default `true` |
+
+**Returns** `ApiResponse_JobSearchResponse_`: the envelope `{ data: JobSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `results` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.listCompanyHiringJobs({ path: { linkedin_company_id: 123 } });
+```
+
+---
+
+<a id="op-listcompanylinkedinposts"></a>
+
+### `g8.api.signals.listCompanyLinkedinPosts(input)`
+
+**List Company Linkedin Posts**
+
+- HTTP: `GET /api/v1/hiring-signals/companies/{linkedin_company_id}/linkedin-posts`
+- operationId: `list_company_linkedin_posts_hiring_signals_companies__linkedin_company_id__linkedin_posts_get` (also callable as `g8.api.call("list_company_linkedin_posts_hiring_signals_companies__linkedin_company_id__linkedin_posts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Recent organic LinkedIn posts from one company.
+
+`window_days` is optional here, unlike on the jobs endpoint: an omitted
+window means "newest regardless of age", not "default of 60". Defaulting
+it would silently hide a company that posts rarely.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.linkedin_company_id` | `integer` | yes | LinkedIn company id (lcid). |
+| `query.limit` | `integer` | no | default `50` |
+| `query.window_days` | `integer \| null` | no | Optional age cap in days. OMIT to get the newest posts regardless of age. |
+
+**Returns** `ApiResponse_JobSearchResponse_`: the envelope `{ data: JobSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `results` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.listCompanyLinkedinPosts({ path: { linkedin_company_id: 123 } });
+```
+
+---
+
+<a id="op-listjobchangesignals"></a>
+
+### `g8.api.signals.listJobChangeSignals(input?)`
+
+**List Job Change Signals**
+
+- HTTP: `GET /api/v1/hiring-signals/job-changes`
+- operationId: `list_job_change_signals_hiring_signals_job_changes_get` (also callable as `g8.api.call("list_job_change_signals_hiring_signals_job_changes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Contacts who changed employer.
+
+Identifying fields are REDACTED unless the key's user holds a Signals
+write capability - these are named people who moved, which is exactly the
+data a read-only role is not meant to export. The capability is resolved
+from the same principal the browser resolves it from.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.contact_id` | `integer \| null` | no | Filter to a single contact. |
+| `query.listener_id` | `string \| null` | no | Filter to a single Talent Moves listener. |
+| `query.since` | `string \| null` | no | Only events detected at or after this ISO timestamp. |
+| `query.limit` | `integer` | no | default `50` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_JobChangeSignalsResponse_`: the envelope `{ data: JobChangeSignalsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobChangeSignalsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `signals` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.listJobChangeSignals();
+```
+
+---
+
+<a id="op-listlisteners"></a>
+
+### `g8.api.signals.listListeners(input?)`
+
+**List Listeners**
+
+- HTTP: `GET /api/v1/social-listeners`
+- operationId: `list_listeners_social_listeners_get` (also callable as `g8.api.call("list_listeners_social_listeners_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Every listener in the org, with its state.
+
+**Input**: none.
+
+**Returns** `ApiResponse_SocialCollection_`: the envelope `{ data: SocialCollection, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialCollection` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.listListeners();
+```
+
+---
+
+<a id="op-listpostsbycontact"></a>
+
+### `g8.api.signals.listPostsByContact(input)`
+
+**List Posts By Contact**
+
+- HTTP: `GET /api/v1/social-listeners/posts/by-contact/{contact_id}`
+- operationId: `list_posts_by_contact_social_listeners_posts_by_contact__contact_id__get` (also callable as `g8.api.call("list_posts_by_contact_social_listeners_posts_by_contact__contact_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Everything one graph8 contact has posted that a listener matched.
+
+Matches on the resolved contact link first and falls back to a
+case-insensitive handle match, so it still finds posts recorded before the
+author was resolved to a contact.
+
+404 for a contact outside the key's record scope - the same answer as a
+contact that does not exist, so the two cannot be told apart.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact id. |
+| `query.limit` | `integer` | no | default `100` |
+
+**Returns** `ApiResponse_SocialCollection_`: the envelope `{ data: SocialCollection, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialCollection` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.listPostsByContact({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-listsourcelists"></a>
+
+### `g8.api.signals.listSourceLists(input?)`
+
+**List Source Lists**
+
+- HTTP: `GET /api/v1/social-listeners/source-lists`
+- operationId: `list_source_lists_social_listeners_source_lists_get` (also callable as `g8.api.call("list_source_lists_social_listeners_source_lists_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+graph8 lists that can be used as the source for `/bulk-from-list`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.audience_type` | `string \| null` | no | Filter to one audience type. |
+| `query.active_only` | `boolean` | no | Only lists still in use. default `true` |
+
+**Returns** `ApiResponse_SocialCollection_`: the envelope `{ data: SocialCollection, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialCollection` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.listSourceLists();
+```
+
+---
+
+<a id="op-listtopengagedaccounts"></a>
+
+### `g8.api.signals.listTopEngagedAccounts(input?)`
+
+**List Top Engaged Accounts**
+
+- HTTP: `GET /api/v1/social-listeners/engagements/top-accounts`
+- operationId: `list_top_engaged_accounts_social_listeners_engagements_top_accounts_get` (also callable as `g8.api.call("list_top_engaged_accounts_social_listeners_engagements_top_accounts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+The accounts that engage with you most often.
+
+The warm-audience view: someone who has commented on four of your posts is
+a different prospect from someone who liked one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | default `30` |
+| `query.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube" \| null` | no |  |
+| `query.min_posts` | `integer` | no | Only accounts that engaged this often. default `2` |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_SocialCollection_`: the envelope `{ data: SocialCollection, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialCollection` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.listTopEngagedAccounts();
+```
+
+---
+
+<a id="op-markpost"></a>
+
+### `g8.api.signals.markPost(input)`
+
+**Mark Post**
+
+- HTTP: `POST /api/v1/social-listeners/posts/{post_id}/mark`
+- operationId: `mark_post_social_listeners_posts__post_id__mark_post` (also callable as `g8.api.call("mark_post_social_listeners_posts__post_id__mark_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Triage a matched post as reviewed or dismissed.
+
+`platform` is part of the identity, not a filter - the same id means
+different posts on different platforms.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's platform-native id. |
+| `body` | `MarkPostRequest` | yes | Request body; fields below. |
+| `query.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"` | no | Which platform the post id belongs to. default `"x"` |
+
+Body fields (`MarkPostRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `"reviewed" \| "dismissed"` | yes |  |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.markPost({ path: { post_id: "id" }, body: { status: "reviewed" } });
+```
+
+---
+
+<a id="op-matchjobchangesignals"></a>
+
+### `g8.api.signals.matchJobChangeSignals(input)`
+
+**Match Job Change Signals**
+
+- HTTP: `POST /api/v1/hiring-signals/job-changes/match`
+- operationId: `match_job_change_signals_hiring_signals_job_changes_match_post` (also callable as `g8.api.call("match_job_change_signals_hiring_signals_job_changes_match_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Which of these LinkedIn profiles changed job in the last 90 days.
+
+A lookup, not a search: it answers a question about a list the caller
+already has, which is why it takes URLs rather than filters.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `JobChangeMatchRequest` | yes | Request body; fields below. |
+
+Body fields (`JobChangeMatchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.linkedin_urls` | `Array<string>` | yes | LinkedIn profile URLs to match against the last 90 days of job-change events. min items 1, max items 1000 |
+
+**Returns** `ApiResponse_JobChangeSignalsResponse_`: the envelope `{ data: JobChangeSignalsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobChangeSignalsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `signals` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.matchJobChangeSignals({ body: { linkedin_urls: ["https://example.com"] } });
+```
+
+---
+
+<a id="op-previewkeywordurls"></a>
+
+### `g8.api.signals.previewKeywordUrls(input)`
+
+**Preview Keyword Urls**
+
+- HTTP: `POST /api/v1/intent/keywords/preview`
+- operationId: `preview_keyword_urls_intent_keywords_preview_post` (also callable as `g8.api.call("preview_keyword_urls_intent_keywords_preview_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Estimate how many URLs a keyword and filters would match, WITHOUT creating it.
+
+Reads pages already crawled; starts no crawl and creates nothing. Returns
+`estimated_url_count`, `baseline_url_count` and a `filter_impact` breakdown.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PreviewKeywordUrlsRequest` | yes | Request body; fields below. |
+
+Body fields (`PreviewKeywordUrlsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keyword` | `string` | yes | The keyword to preview. min length 1 |
+| `body.search_filters` | `KeywordFilters` | no | Filters to preview it with. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.previewKeywordUrls({ body: { keyword: "example" } });
+```
+
+---
+
+<a id="op-previewlistenercost"></a>
+
+### `g8.api.signals.previewListenerCost(input)`
+
+**Preview Listener Cost**
+
+- HTTP: `POST /api/v1/social-listeners/preview-cost`
+- operationId: `preview_listener_cost_social_listeners_preview_cost_post` (also callable as `g8.api.call("preview_listener_cost_social_listeners_preview_cost_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+What a listener WOULD cost per month. CHARGES NOTHING.
+
+A pure estimate: it samples at most ten results to project a posts-per-day
+rate, caches the answer for an hour, and returns arithmetic.
+`credits_per_month_estimate` is a projection for a listener that does not
+exist yet, not a debit.
+
+Tiered `read` for that reason, so a read-only key can find out what
+something costs before anyone commits to it. POST only because the query is
+a body.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PreviewCostRequest` | yes | Request body; fields below. |
+
+Body fields (`PreviewCostRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.listener_type` | `"brand" \| "competitor" \| "keyword" \| "engagement" \| "user"` | yes |  |
+| `body.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"` | no | default `"x"` |
+| `body.poll_interval_sec` | `integer` | no | The interval to cost. Shorter intervals cost more. default `600`, min 60 |
+| `body.query` | `string \| null` | no |  |
+| `body.target_handle` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.previewListenerCost({ body: { listener_type: "brand" } });
+```
+
+---
+
+<a id="op-proposehiringkeywords"></a>
+
+### `g8.api.signals.proposeHiringKeywords(input)`
+
+**Propose Hiring Keywords**
+
+- HTTP: `POST /api/v1/intent/keywords/auto-seed-proposals`
+- operationId: `propose_hiring_keywords_intent_keywords_auto_seed_proposals_post` (also callable as `g8.api.call("propose_hiring_keywords_intent_keywords_auto_seed_proposals_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Propose hiring listeners from the org's own personas and ICP.
+
+PROPOSALS, not keywords: nothing is created - add the ones you want with
+`POST /intent/keywords/add`. Generating them runs a model, so the org must
+have credit (402 otherwise). Falls back to a starter set when the org has no
+context documents yet.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AutoSeedProposalsRequest` | yes | Request body; fields below. |
+
+Body fields (`AutoSeedProposalsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.signal_type` | `"jobs" \| "job_changes"` | no | `jobs` (Hiring Wave) or `job_changes` (Talent Moves). default `"jobs"` |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.proposeHiringKeywords({ body: {} });
+```
+
+---
+
+<a id="op-resolvehiringcompanyids"></a>
+
+### `g8.api.signals.resolveHiringCompanyIds(input)`
+
+**Resolve Hiring Company Ids**
+
+- HTTP: `POST /api/v1/hiring-signals/companies/resolve-ids`
+- operationId: `resolve_hiring_company_ids_hiring_signals_companies_resolve_ids_post` (also callable as `g8.api.call("resolve_hiring_company_ids_hiring_signals_companies_resolve_ids_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Turn LinkedIn company ids into graph8 company ids.
+
+This is the step that makes a Hiring Signals result usable: the search
+returns lcids, and building a list or enrolling a sequence needs graph8
+ids. The handler caps the input server-side regardless of what is sent.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ResolveCompanyIdsRequest` | yes | Request body; fields below. |
+
+Body fields (`ResolveCompanyIdsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.linkedin_company_ids` | `Array<integer>` | no |  |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.resolveHiringCompanyIds({ body: {} });
+```
+
+---
+
+<a id="op-resolvejobsforkeyword"></a>
+
+### `g8.api.signals.resolveJobsForKeyword(input)`
+
+**Resolve Jobs For Keyword**
+
+- HTTP: `POST /api/v1/intent/keywords/{keyword_id}/job-resolution`
+- operationId: `resolve_jobs_for_keyword_intent_keywords__keyword_id__job_resolution_post` (also callable as `g8.api.call("resolve_jobs_for_keyword_intent_keywords__keyword_id__job_resolution_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Run the jobs resolver for this keyword NOW, instead of waiting for the hourly run.
+
+Synchronous: returns the decision makers and recruiters emitted and the
+wall time taken.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes | The keyword's id. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.resolveJobsForKeyword({ path: { keyword_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-rollupabmcompanies"></a>
+
+### `g8.api.signals.rollupAbmCompanies(input)`
+
+**Rollup Abm Companies**
+
+- HTTP: `POST /api/v1/intent/abm/rollup`
+- operationId: `rollup_abm_companies_intent_abm_rollup_post` (also callable as `g8.api.call("rollup_abm_companies_intent_abm_rollup_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Account strength, high-intent flag and persona coverage for up to 500 named companies.
+
+A read: POST only because the id list is a body. Returned under `rollups`,
+keyed by company id.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `AbmRollupRequest` | yes | Request body; fields below. |
+
+Body fields (`AbmRollupRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.company_ids` | `Array<integer>` | yes | Company ids, at most 500 per call - the app refuses more; chunk larger sets. max items 500 |
+| `body.days` | `integer` | no | Look-back window in days. default `30` |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.signals.rollupAbmCompanies({ body: { company_ids: [123] } });
+```
+
+---
+
+<a id="op-saveintenttocontactmetadata"></a>
+
+### `g8.api.signals.saveIntentToContactMetadata(input)`
+
+**Save Intent To Contact Metadata**
+
+- HTTP: `POST /api/v1/intent/contacts/metadata`
+- operationId: `save_intent_to_contact_metadata_intent_contacts_metadata_post` (also callable as `g8.api.call("save_intent_to_contact_metadata_intent_contacts_metadata_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Write each contact's resolved intent onto the contact record, in the background.
+
+202: the work runs after the response, on THIS request's own background
+tasks. The org is always the key's own; `force_update` overwrites intent
+metadata already present instead of only filling gaps.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SaveIntentToMetadataRequest` | yes | Request body; fields below. |
+
+Body fields (`SaveIntentToMetadataRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.force_update` | `boolean` | no | Overwrite intent metadata already on a contact, rather than only filling gaps. default `false` |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.saveIntentToContactMetadata({ body: {} });
+```
+
+---
+
+<a id="op-savekeywordsyncconfig"></a>
+
+### `g8.api.signals.saveKeywordSyncConfig(input)`
+
+**Save Keyword Sync Config**
+
+- HTTP: `PATCH /api/v1/intent/keywords/{keyword_id}/sync-config`
+- operationId: `save_keyword_sync_config_intent_keywords__keyword_id__sync_config_patch` (also callable as `g8.api.call("save_keyword_sync_config_intent_keywords__keyword_id__sync_config_patch", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Wire this keyword to a list (upsert).
+
+`auto_sync_enabled: true` is the consequential field: from then on the
+keyword's matches are pushed into `list_id` on a schedule, and anything
+downstream of that list runs on the people it found.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes | The keyword's id. |
+| `body` | `KeywordSyncConfigRequest` | yes | Request body; fields below. |
+
+Body fields (`KeywordSyncConfigRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.auto_sync_enabled` | `boolean` | no | Push on a schedule, without anyone calling anything, rather than only on request. default `false` |
+| `body.committee_id` | `string (uuid) \| null` | no | Buying committee whose personas are exported. |
+| `body.export_mode` | `"signals_only" \| "icp_plus_signals" \| "all_icp_personas"` | no | `signals_only` exports only the people a signal named; `icp_plus_signals` adds the ICP's personas at those companies; `all_icp_personas` exports every persona regardless of signal. default `"icp_plus_signals"` |
+| `body.icp_id` | `string (uuid) \| null` | no | Score matches against this ICP. |
+| `body.list_id` | `integer \| null` | no | The list matches are pushed into. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.saveKeywordSyncConfig({
+  path: { keyword_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-savepostauthorascontact"></a>
+
+### `g8.api.signals.savePostAuthorAsContact(input)`
+
+**Save Post Author As Contact**
+
+- HTTP: `POST /api/v1/social-listeners/posts/{post_id}/save-contact`
+- operationId: `save_post_author_as_contact_social_listeners_posts__post_id__save_contact_post` (also callable as `g8.api.call("save_post_author_as_contact_social_listeners_posts__post_id__save_contact_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Turn one post's author into a graph8 contact.
+
+Resolves an existing contact where there is one rather than duplicating.
+No enrichment happens here and no credit is spent - the contact is created
+from what the post already carries.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's platform-native id. |
+| `query.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"` | no | default `"x"` |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.savePostAuthorAsContact({ path: { post_id: "id" } });
+```
+
+---
+
+<a id="op-searchhiringaggregators"></a>
+
+### `g8.api.signals.searchHiringAggregators(input)`
+
+**Search Hiring Aggregators**
+
+- HTTP: `POST /api/v1/hiring-signals/aggregators`
+- operationId: `search_hiring_aggregators_hiring_signals_aggregators_post` (also callable as `g8.api.call("search_hiring_aggregators_hiring_signals_aggregators_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+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.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `JobSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`JobSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keywords` | `Array<string>` | yes | Job-title keywords. OR semantics - any match counts. min items 1 |
+| `body.contacts_per_company` | `integer` | no | default `10`, min 1, max 50 |
+| `body.exclude_aggregators` | `boolean` | no | 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. default `true` |
+| `body.include_recruiters` | `boolean` | no | Run the recruiter aggregation and enrichment hop. Set false to skip two round-trips when only Companies and Decision-makers are needed. default `true` |
+| `body.limit` | `integer` | no | Page size. Capped at 200 to bound the ClickHouse cost. default `50`, min 1, max 200 |
+| `body.location_contains` | `string \| null` | no | Free-text token matched case-insensitively against the job location. |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+| `body.parent_linkedin_company_id` | `integer \| null` | no | Scope to one parent company and its subsidiaries. Omit to search everywhere. |
+| `body.per_company_cap` | `integer` | no | Max postings counted per company. default `50`, min 1, max 10000 |
+| `body.persona_department` | `Array<string> \| null` | no | Decision-maker department filter. |
+| `body.persona_seniority` | `Array<string> \| null` | no | Decision-maker seniority filter. |
+| `body.persona_title_contains` | `string \| null` | no | Decision-maker title substring filter. |
+| `body.recruiter_limit` | `integer` | no | 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. default `50`, min 1, max 200 |
+| `body.recruiter_offset` | `integer` | no | default `0`, min 0 |
+| `body.window_days` | `integer` | no | How far back to look for postings. default `30`, min 1, max 365 |
+
+**Returns** `ApiResponse_JobSearchResponse_`: the envelope `{ data: JobSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `results` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.searchHiringAggregators({ body: { keywords: ["example"] } });
+```
+
+---
+
+<a id="op-searchhiringcompanies"></a>
+
+### `g8.api.signals.searchHiringCompanies(input)`
+
+**Search Hiring Companies**
+
+- HTTP: `POST /api/v1/hiring-signals/companies`
+- operationId: `search_hiring_companies_hiring_signals_companies_post` (also callable as `g8.api.call("search_hiring_companies_hiring_signals_companies_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+The companies behind those postings, rolled up.
+
+`per_company_cap` bounds how many of one company's postings count toward
+its score, so a company with 400 open roles does not drown the ranking.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `JobSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`JobSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keywords` | `Array<string>` | yes | Job-title keywords. OR semantics - any match counts. min items 1 |
+| `body.contacts_per_company` | `integer` | no | default `10`, min 1, max 50 |
+| `body.exclude_aggregators` | `boolean` | no | 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. default `true` |
+| `body.include_recruiters` | `boolean` | no | Run the recruiter aggregation and enrichment hop. Set false to skip two round-trips when only Companies and Decision-makers are needed. default `true` |
+| `body.limit` | `integer` | no | Page size. Capped at 200 to bound the ClickHouse cost. default `50`, min 1, max 200 |
+| `body.location_contains` | `string \| null` | no | Free-text token matched case-insensitively against the job location. |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+| `body.parent_linkedin_company_id` | `integer \| null` | no | Scope to one parent company and its subsidiaries. Omit to search everywhere. |
+| `body.per_company_cap` | `integer` | no | Max postings counted per company. default `50`, min 1, max 10000 |
+| `body.persona_department` | `Array<string> \| null` | no | Decision-maker department filter. |
+| `body.persona_seniority` | `Array<string> \| null` | no | Decision-maker seniority filter. |
+| `body.persona_title_contains` | `string \| null` | no | Decision-maker title substring filter. |
+| `body.recruiter_limit` | `integer` | no | 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. default `50`, min 1, max 200 |
+| `body.recruiter_offset` | `integer` | no | default `0`, min 0 |
+| `body.window_days` | `integer` | no | How far back to look for postings. default `30`, min 1, max 365 |
+
+**Returns** `ApiResponse_JobSearchResponse_`: the envelope `{ data: JobSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `results` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.searchHiringCompanies({ body: { keywords: ["example"] } });
+```
+
+---
+
+<a id="op-searchhiringdecisionmakers"></a>
+
+### `g8.api.signals.searchHiringDecisionMakers(input)`
+
+**Search Hiring Decision Makers**
+
+- HTTP: `POST /api/v1/hiring-signals/decision-makers`
+- operationId: `search_hiring_decision_makers_hiring_signals_decision_makers_post` (also callable as `g8.api.call("search_hiring_decision_makers_hiring_signals_decision_makers_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+People to talk to at the hiring companies.
+
+Scoped by the `persona_*` filters, capped per company by
+`contacts_per_company` - the point is a shortlist per account, not every
+employee.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `JobSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`JobSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keywords` | `Array<string>` | yes | Job-title keywords. OR semantics - any match counts. min items 1 |
+| `body.contacts_per_company` | `integer` | no | default `10`, min 1, max 50 |
+| `body.exclude_aggregators` | `boolean` | no | 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. default `true` |
+| `body.include_recruiters` | `boolean` | no | Run the recruiter aggregation and enrichment hop. Set false to skip two round-trips when only Companies and Decision-makers are needed. default `true` |
+| `body.limit` | `integer` | no | Page size. Capped at 200 to bound the ClickHouse cost. default `50`, min 1, max 200 |
+| `body.location_contains` | `string \| null` | no | Free-text token matched case-insensitively against the job location. |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+| `body.parent_linkedin_company_id` | `integer \| null` | no | Scope to one parent company and its subsidiaries. Omit to search everywhere. |
+| `body.per_company_cap` | `integer` | no | Max postings counted per company. default `50`, min 1, max 10000 |
+| `body.persona_department` | `Array<string> \| null` | no | Decision-maker department filter. |
+| `body.persona_seniority` | `Array<string> \| null` | no | Decision-maker seniority filter. |
+| `body.persona_title_contains` | `string \| null` | no | Decision-maker title substring filter. |
+| `body.recruiter_limit` | `integer` | no | 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. default `50`, min 1, max 200 |
+| `body.recruiter_offset` | `integer` | no | default `0`, min 0 |
+| `body.window_days` | `integer` | no | How far back to look for postings. default `30`, min 1, max 365 |
+
+**Returns** `ApiResponse_JobSearchResponse_`: the envelope `{ data: JobSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `results` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.searchHiringDecisionMakers({ body: { keywords: ["example"] } });
+```
+
+---
+
+<a id="op-searchhiringjobs"></a>
+
+### `g8.api.signals.searchHiringJobs(input)`
+
+**Search Hiring Jobs**
+
+- HTTP: `POST /api/v1/hiring-signals/jobs`
+- operationId: `search_hiring_jobs_hiring_signals_jobs_post` (also callable as `g8.api.call("search_hiring_jobs_hiring_signals_jobs_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Raw job postings matching the keywords. The default view.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `JobSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`JobSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keywords` | `Array<string>` | yes | Job-title keywords. OR semantics - any match counts. min items 1 |
+| `body.contacts_per_company` | `integer` | no | default `10`, min 1, max 50 |
+| `body.exclude_aggregators` | `boolean` | no | 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. default `true` |
+| `body.include_recruiters` | `boolean` | no | Run the recruiter aggregation and enrichment hop. Set false to skip two round-trips when only Companies and Decision-makers are needed. default `true` |
+| `body.limit` | `integer` | no | Page size. Capped at 200 to bound the ClickHouse cost. default `50`, min 1, max 200 |
+| `body.location_contains` | `string \| null` | no | Free-text token matched case-insensitively against the job location. |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+| `body.parent_linkedin_company_id` | `integer \| null` | no | Scope to one parent company and its subsidiaries. Omit to search everywhere. |
+| `body.per_company_cap` | `integer` | no | Max postings counted per company. default `50`, min 1, max 10000 |
+| `body.persona_department` | `Array<string> \| null` | no | Decision-maker department filter. |
+| `body.persona_seniority` | `Array<string> \| null` | no | Decision-maker seniority filter. |
+| `body.persona_title_contains` | `string \| null` | no | Decision-maker title substring filter. |
+| `body.recruiter_limit` | `integer` | no | 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. default `50`, min 1, max 200 |
+| `body.recruiter_offset` | `integer` | no | default `0`, min 0 |
+| `body.window_days` | `integer` | no | How far back to look for postings. default `30`, min 1, max 365 |
+
+**Returns** `ApiResponse_JobSearchResponse_`: the envelope `{ data: JobSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `results` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.searchHiringJobs({ body: { keywords: ["example"] } });
+```
+
+---
+
+<a id="op-searchhiringrecruiters"></a>
+
+### `g8.api.signals.searchHiringRecruiters(input)`
+
+**Search Hiring Recruiters**
+
+- HTTP: `POST /api/v1/hiring-signals/recruiters`
+- operationId: `search_hiring_recruiters_hiring_signals_recruiters_post` (also callable as `g8.api.call("search_hiring_recruiters_hiring_signals_recruiters_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+The recruiters who posted the matching jobs.
+
+Paged by `recruiter_limit`/`recruiter_offset`, INDEPENDENTLY of the
+companies paging: one recruiter can serve many companies, so the two
+counts diverge and paging one must not move the other.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `JobSearchRequest` | yes | Request body; fields below. |
+
+Body fields (`JobSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keywords` | `Array<string>` | yes | Job-title keywords. OR semantics - any match counts. min items 1 |
+| `body.contacts_per_company` | `integer` | no | default `10`, min 1, max 50 |
+| `body.exclude_aggregators` | `boolean` | no | 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. default `true` |
+| `body.include_recruiters` | `boolean` | no | Run the recruiter aggregation and enrichment hop. Set false to skip two round-trips when only Companies and Decision-makers are needed. default `true` |
+| `body.limit` | `integer` | no | Page size. Capped at 200 to bound the ClickHouse cost. default `50`, min 1, max 200 |
+| `body.location_contains` | `string \| null` | no | Free-text token matched case-insensitively against the job location. |
+| `body.offset` | `integer` | no | default `0`, min 0 |
+| `body.parent_linkedin_company_id` | `integer \| null` | no | Scope to one parent company and its subsidiaries. Omit to search everywhere. |
+| `body.per_company_cap` | `integer` | no | Max postings counted per company. default `50`, min 1, max 10000 |
+| `body.persona_department` | `Array<string> \| null` | no | Decision-maker department filter. |
+| `body.persona_seniority` | `Array<string> \| null` | no | Decision-maker seniority filter. |
+| `body.persona_title_contains` | `string \| null` | no | Decision-maker title substring filter. |
+| `body.recruiter_limit` | `integer` | no | 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. default `50`, min 1, max 200 |
+| `body.recruiter_offset` | `integer` | no | default `0`, min 0 |
+| `body.window_days` | `integer` | no | How far back to look for postings. default `30`, min 1, max 365 |
+
+**Returns** `ApiResponse_JobSearchResponse_`: the envelope `{ data: JobSearchResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`JobSearchResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `results` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.searchHiringRecruiters({ body: { keywords: ["example"] } });
+```
+
+---
+
+<a id="op-searchmatchedposts"></a>
+
+### `g8.api.signals.searchMatchedPosts(input)`
+
+**Search Matched Posts**
+
+- HTTP: `POST /api/v1/social-listeners/posts/search`
+- operationId: `search_matched_posts_social_listeners_posts_search_post` (also callable as `g8.api.call("search_matched_posts_social_listeners_posts_search_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Posts the listeners have already matched.
+
+A PAGINATED DATABASE READ. It makes no live platform call and spends
+nothing - the fetching is done by the polling worker, not by this call. The
+app spells it `/fetch`, which reads like it goes and gets them; it does
+not, and the path here says so.
+
+Tiered `read` for the same reason: a key granted "read my signals" has to
+be able to read a matched post.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SearchPostsRequest` | yes | Request body; fields below. |
+
+Body fields (`SearchPostsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.conditions` | `Array<Record<string, unknown>>` | no | Grid-style filter expressions, passed through unchanged. Their grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. |
+| `body.has_contact` | `boolean \| null` | no | Only posts whose author resolved to a graph8 contact. |
+| `body.hide_low_confidence` | `boolean \| null` | no | Hide posts the classifier scored confidently LOW (< 0.5), while keeping never-classified ones visible. Not the same as `min_score=0.5`, which would also hide the unscored. |
+| `body.limit` | `integer` | no | default `100`, min 1, max 200 |
+| `body.listener_id` | `string (uuid) \| null` | no |  |
+| `body.max_score` | `number \| null` | no | min 0, max 1 |
+| `body.min_score` | `number \| null` | no | min 0, max 1 |
+| `body.page` | `integer` | no | default `1`, min 1 |
+| `body.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube" \| null` | no |  |
+| `body.since` | `string (date-time) \| null` | no |  |
+| `body.status` | `string \| null` | no | `new`, `reviewed` or `dismissed`. |
+| `body.until` | `string (date-time) \| null` | no |  |
+
+**Returns** `ApiResponse_SocialCollection_`: the envelope `{ data: SocialCollection, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialCollection` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.searchMatchedPosts({ body: {} });
+```
+
+---
+
+<a id="op-searchpostengagements"></a>
+
+### `g8.api.signals.searchPostEngagements(input)`
+
+**Search Post Engagements**
+
+- HTTP: `POST /api/v1/social-listeners/posts/{post_id}/engagements/search`
+- operationId: `search_post_engagements_social_listeners_posts__post_id__engagements_search_post` (also callable as `g8.api.call("search_post_engagements_social_listeners_posts__post_id__engagements_search_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+Who commented on or reacted to one matched post.
+
+Also a paginated database read - the engagements were stored by the worker,
+and only when `fetch_engagements` is on for that channel. An empty result
+can mean "nobody engaged" OR "engagement fetching is off"; check
+`GET /social-listeners/settings`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.post_id` | `string` | yes | The post's platform-native id. |
+| `body` | `SearchPostEngagementsRequest` | yes | Request body; fields below. |
+
+Body fields (`SearchPostEngagementsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.engagement_type` | `"comment" \| "reaction" \| null` | no |  |
+| `body.limit` | `integer` | no | default `100`, min 1, max 200 |
+| `body.page` | `integer` | no | default `1`, min 1 |
+| `body.platform` | `"x" \| "linkedin" \| "reddit" \| "instagram" \| "youtube"` | no | default `"x"` |
+
+**Returns** `ApiResponse_SocialCollection_`: the envelope `{ data: SocialCollection, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SocialCollection` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.signals.searchPostEngagements({ path: { post_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-testxcredentials"></a>
+
+### `g8.api.signals.testXCredentials(input)`
+
+**Test X Credentials**
+
+- HTTP: `POST /api/v1/social-listeners/integrations/x/test`
+- operationId: `test_x_credentials_social_listeners_integrations_x_test_post` (also callable as `g8.api.call("test_x_credentials_social_listeners_integrations_x_test_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Check credentials against X without storing them.
+
+Persists NOTHING, whether the check passes or fails. Run this before
+`POST /social-listeners/integrations/x` so a typo does not pause every
+listener the org has.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `XApiCredentialsRequest` | yes | Request body; fields below. |
+
+Body fields (`XApiCredentialsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.api_key` | `string` | yes | X Developer App API key (consumer key). min length 1 |
+| `body.api_secret` | `string` | yes | X Developer App API secret. min length 1 |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.testXCredentials({ body: { api_key: "example", api_secret: "example" } });
+```
+
+---
+
+<a id="op-triggerkeywordsync"></a>
+
+### `g8.api.signals.triggerKeywordSync(input)`
+
+**Trigger Keyword Sync**
+
+- HTTP: `POST /api/v1/intent/keywords/{keyword_id}/sync`
+- operationId: `trigger_keyword_sync_intent_keywords__keyword_id__sync_post` (also callable as `g8.api.call("trigger_keyword_sync_intent_keywords__keyword_id__sync_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Queue an immediate sync of this keyword's matches into its configured list.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes | The keyword's id. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.triggerKeywordSync({ path: { keyword_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-updatehiringkeyword"></a>
+
+### `g8.api.signals.updateHiringKeyword(input)`
+
+**Update Hiring Keyword**
+
+- HTTP: `PATCH /api/v1/intent/keywords/{keyword_id}`
+- operationId: `update_hiring_keyword_intent_keywords__keyword_id__patch` (also callable as `g8.api.call("update_hiring_keyword_intent_keywords__keyword_id__patch", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Edit a HIRING listener in place: its name, filters or watchlist scope.
+
+Only `jobs` and `job_changes` listeners are editable here; any other keyword
+is a 404. `search_filters` is a FULL REPLACEMENT.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.keyword_id` | `string (uuid)` | yes | The keyword's id. |
+| `body` | `UpdateKeywordRequest` | yes | Request body; fields below. |
+
+Body fields (`UpdateKeywordRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.keyword` | `string \| null` | no | The listener's name. Must not be blank. |
+| `body.search_filters` | `Record<string, unknown> \| null` | no | FULL REPLACEMENT of the filter object, not a merge - filters left out are dropped. `window_days` must be 1-365 and `contacts_per_company` 1-50 when present. |
+| `body.watchlist_source` | `string \| null` | no | Talent Moves watchlist scope, as a JSON-encoded string. |
+
+**Returns** `ApiResponse_IntentPayload_`: the envelope `{ data: IntentPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.updateHiringKeyword({
+  path: { keyword_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-updatelistener"></a>
+
+### `g8.api.signals.updateListener(input)`
+
+**Update Listener**
+
+- HTTP: `PATCH /api/v1/social-listeners/{listener_id}`
+- operationId: `update_listener_social_listeners__listener_id__patch` (also callable as `g8.api.call("update_listener_social_listeners__listener_id__patch", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Partial update. Omitted fields are left alone.
+
+`is_active: false` pauses polling without losing the listener or its
+history - the way to stop spend without destroying what has been matched.
+
+Changing `target_handle` on a `user` listener re-resolves the account
+against the platform, which consumes X API quota.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.listener_id` | `string (uuid)` | yes | The listener's id. |
+| `body` | `PatchListenerRequest` | yes | Request body; fields below. |
+
+Body fields (`PatchListenerRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.filters` | `Record<string, unknown> \| null` | no |  |
+| `body.is_active` | `boolean \| null` | no | False pauses polling without deleting the listener. |
+| `body.monthly_credit_cap` | `integer \| null` | no | min 0 |
+| `body.name` | `string \| null` | no |  |
+| `body.poll_interval_sec` | `integer \| null` | no | min 60 |
+| `body.query` | `string \| null` | no |  |
+| `body.target_handle` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.updateListener({
+  path: { listener_id: "00000000-0000-0000-0000-000000000000" },
+  body: {},
+});
+```
+
+---
+
+<a id="op-updatesocialsettings"></a>
+
+### `g8.api.signals.updateSocialSettings(input)`
+
+**Update Social Settings**
+
+- HTTP: `PATCH /api/v1/social-listeners/settings`
+- operationId: `update_social_settings_social_listeners_settings_patch` (also callable as `g8.api.call("update_social_settings_social_listeners_settings_patch", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `intent:run`
+
+Change the org's spend ceilings and capture rules.
+
+ADMIN ONLY, and gated twice for two different reasons. The app declares
+`require_signals_write` as a dependency AND checks
+`user.has_role_in_org(org_id, "Admin")` in its BODY. That second check
+reads `User.roles`, which `get_api_user` never populates - so for an API
+key it answers False no matter who minted it. `require_org_admin` is the
+API-key-native half and `with_org_role` makes the app's own half answer
+correctly rather than refusing everyone.
+
+This is the surface that BOUNDS what social listening costs. Raising
+`monthly_credit_cap` or turning `auto_pause_on_cap` off removes the brake.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `PatchSocialSettingsRequest` | yes | Request body; fields below. |
+
+Body fields (`PatchSocialSettingsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.alert_threshold_pct` | `integer \| null` | no | Alert at this percentage of the cap. min 0, max 100 |
+| `body.auto_archive_days` | `integer \| null` | no | min 0 |
+| `body.auto_create_contacts` | `boolean \| null` | no |  |
+| `body.auto_pause_on_cap` | `boolean \| null` | no | Stop polling when the cap is reached, rather than alerting. |
+| `body.channel_settings` | `Record<string, ChannelSettingsRule> \| null` | no | Keyed by platform. Keys the app does not recognise are dropped by its own merge - it rebuilds the map from the supported set. |
+| `body.classifier_model` | `string \| null` | no |  |
+| `body.contact_capture` | `Record<string, ContactCaptureRule> \| null` | no |  |
+| `body.monthly_credit_cap` | `integer \| null` | no | min 0 |
+| `body.other_channels_monthly_credit_cap` | `integer \| null` | no | Org-wide monthly credit ceiling across the non-X channels (LinkedIn, Reddit, Instagram, YouTube) together. 0 means no org-wide ceiling; the per-channel caps in `channel_settings` still apply. min 0 |
+
+**Returns** `ApiResponse_SocialPayload_`: the envelope `{ data: SocialPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.signals.updateSocialSettings({ body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-channelsettingsrule"></a>
+
+### `ChannelSettingsRule`
+
+Per-channel spend and volume ceilings.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | no | default `true` |
+| `fetch_engagements` | `boolean` | no | Fetch who engaged with each matched post. Multiplies what a poll costs. default `false` |
+| `max_comments_per_post` | `integer` | no | default `50`, min 0 |
+| `max_reactions_per_post` | `integer` | no | default `100`, min 0 |
+| `monthly_credit_cap` | `integer` | no | default `0`, min 0 |
+| `per_poll_result_cap` | `integer` | no | default `50`, min 0 |
+
+<a id="type-contactcapturerule"></a>
+
+### `ContactCaptureRule`
+
+When a matched post's author becomes a graph8 contact.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | no | default `true` |
+| `min_followers` | `integer` | no | default `0`, min 0 |
+| `only_when_classified` | `boolean` | no | default `false` |
+
+<a id="type-keywordfilters"></a>
+
+### `KeywordFilters`
+
+The filters a keyword's URL set is shaped by. Mirrors the app's `KeywordSearchFilters`, including its bounds. Keys beyond the typed ones are accepted and passed through, as the app accepts them.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `audience` | `"b2b" \| "b2c" \| "both"` | no | `b2b`, `b2c` or `both`. default `"both"` |
+| `exclude_domains` | `Array<string>` | no | Domains to drop. |
+| `exclude_page_types` | `Array<"news" \| "finance" \| "forum" \| "vendor_marketing">` | no | Page types to drop from the URL set. |
+| `llm_triage` | `boolean` | no | Run a model pass over candidate pages. default `false` |
+| `max_urls_per_domain` | `integer` | no | Soft cap so no single domain dominates the set. default `5`, min 1, max 20 |
+| `min_commercial_intent_level` | `integer` | no | Drop pages scored below this commercial intent. default `0`, min 0, max 100 |