API reference

The team's Engagement Agent: the profile it targets, its daily credit limit and how that is split (`plan`), whether it is running, its one-off people search and whether that search's people have been added, and every source it set up. `{ "agent": null }` when the team has never set one up. Read-only. `agents` lists every agent the team holds; `agentId` picks one.

Authenticated with the X-API-Key header.

{
  "agent": {
    "status": "active",
    "website": "acme.com",
    "profile": {
      "summary": "Sales engagement software for B2B teams.",
      "titles": [
        "VP Sales",
        "Head of Growth"
      ],
      "industries": [
        "Software Development"
      ],
      "companySizes": [
        "51-200",
        "201-500"
      ],
      "countries": [
        "United Kingdom"
      ],
      "topics": [
        "cold email",
        "AI SDR"
      ],
      "competitors": [
        {
          "name": "Outreach",
          "domain": "outreach.io"
        }
      ]
    },
    "dailyCredits": 1000,
    "plan": {
      "perTopic": 250,
      "people": 20,
      "total": 1000
    },
    "launchedAt": "2026-10-06T09:00:00.000Z",
    "discoverRun": "8a1c0b2e-4f3d-4c55-9e0a-2b7d1f6c9a10",
    "peopleAdded": true,
    "sources": [
      {
        "id": "5c0e6a7b-1d2f-4e3a-8b9c-0d1e2f3a4b5c",
        "type": "keyword",
        "label": "cold email",
        "active": true
      },
      {
        "id": "9f8e7d6c-5b4a-4321-8fed-cba987654321",
        "type": "person",
        "label": "Jane Doe",
        "active": true
      }
    ]
  }
}

A PARTIAL update of the website, the profile's parts and the daily limit: only the fields sent change. Creates the agent as a draft when the team has none. Starts nothing and charges nothing: a running agent keeps its sources and caps until POST /api/v1/agent/start runs again. The body is flat: `topics`, `titles` and the rest sit beside `website` and `dailyCredits`, and come back under `agent.profile`. Drafting a profile from the website is a dashboard-only step, so callers set the parts themselves. Also sets the agent's webhook, and `create: true` adds another agent.

Authenticated with the X-API-Key header.

{
  "website": "acme.com",
  "titles": [
    "VP Sales",
    "Head of Growth"
  ],
  "industries": [
    "Software Development"
  ],
  "companySizes": [
    "51-200",
    "201-500"
  ],
  "countries": [
    "United Kingdom"
  ],
  "topics": [
    "cold email",
    "AI SDR"
  ],
  "dailyCredits": 1000
}

The dashboard's launch, server side. It first STOPS every source the agent set up before (the soft untrack DELETE /api/v1/keyword/{id} and /profile/{username} run, so their leads are kept), then creates one daily keyword search per topic, named `Agent: <topic>`, past week, capturing the people who engage, each capped at `plan.perTopic` (a live search the team already has on a topic is reused and never re-capped), and starts a one-off people search: a Discover run on the first 10 topics for the most engaged people posting about them, capped at `plan.people`. WHEN THAT SEARCH FINISHES, THE WORKER ADDS ITS PEOPLE as watched profiles (25 credits a sync each, a 5-post first sync); `agent.peopleAdded` turns true then. THE AGENT RECURS: every topic search runs daily and every watched person syncs daily until POST /api/v1/agent/stop, so `plan.total` is a standing daily commitment. Billing: one credit per new person any of its sources captures, whether or not they match the profile. Without `"confirmSpend": true` the call is refused 409 `spend_confirmation_required` with the figures, and nothing is stopped or created. Each topic search goes through POST /api/v1/keyword/track's own checks (balance, trial limits); one that is refused is listed in `launch.failed` and the rest start. On a free trial the agent checks 1,000 people in all on its own allowance: its topic searches and people never use the trial's own keyword or profile slots.

Authenticated with the X-API-Key header.

{
  "dailyCredits": 1000,
  "confirmSpend": true
}

Untracks every active source the agent set up (the same soft untrack the DELETE routes run), so none of them runs or charges again, and sets the agent back to `draft`. The leads they captured are kept and GET /api/v1/agent/leads still serves them. A people search already running finishes, but its people are not added once the agent is stopped. A trial team's own sources cannot be untracked and are listed in `stop.notStopped`. Takes only an optional `agentId`.

Authenticated with the X-API-Key header.

Agent Leads: the people the agent's sources captured, one row per person. Agent Leads is RANKED, one row per person: the job title must match (it gates); everything else lowers the ICP % (title 40, country 30, industry 15, company size 15; a part enrichment could not fill earns half; parts left empty are not counted), from 40 to 100. Each person's signal is extra_strong (engaged twice or more), strong (a comment on a post about the topics, a comment on a lead-magnet post, or a 100% ICP match on a post about the topics), medium (any other engagement) or weak (only an engagement with a hiring post or personal news). Ranked by ICP %, then signal, then newest: exactly the dashboard's Agent Leads table, built by the same code. `checked` is everyone the sources captured, which is what the team paid for; `total` is how many show. `firstRun.done` is false while the first run is still going. `filters` narrows the list as the table's Filters button does. Leads of a source the agent later stopped are kept and listed. Reads the newest 5,000 captured leads.

Authenticated with the X-API-Key header.

The dashboard's "Push historic leads": without `leadIds`, every Agent Lead that passes the webhook's own filters; with them, those leads. Each is marked for delivery and sent as one signed POST, retried like the team's other webhooks, from the agent's sources that carry its URL. A lead already sent or on its way is not sent again. New leads go by themselves while the webhook's autoSend is on. Charges no credits.

Authenticated with the X-API-Key header.

Whether the team has connected HeyReach, when, whether HeyReach has since rejected the key (`keyRejected`: auto-push waits until the key is reconnected on the dashboard's Integrations page), and every auto-push rule with its state. Connecting a key is dashboard-only, like API keys: the API never takes, returns or logs one. Charges nothing.

Authenticated with the X-API-Key header.

The team's HeyReach campaigns that leads can join, read live from HeyReach with the team's stored key: in progress, paused, draft, scheduled or starting (finished, canceled and failed ones are left out). `canTakeLeads` is false for a campaign with no LinkedIn sender yet. Charges nothing.

Authenticated with the X-API-Key header.

Add leads to a HeyReach campaign, where its LinkedIn outreach starts. Send `leadIds` (from GET /api/v1/leads or /api/v1/agent/leads; with `agentId` each Agent Lead also carries its ICP % and signal) or `people` (influencers found by Discover, which have no lead row: their profile URL, name, title, company and country are sent as given), at most 1,000 a call. Only ENRICHED leads are sent; a lead with no LinkedIn profile URL is skipped (`skippedNoLinkedin`); a person is never sent twice to the same campaign (`alreadyInCampaign`); a paused campaign is never resumed, and a finished one is never restarted. HeyReach receives name, job title, company, country, work email (when found), the LinkedIn profile URL and the headline (as `summary`), plus custom fields `icp_percent`, `signal`, `engaged_post_url`, `comment_text` and `source_name` where known. Charges no credits.

Authenticated with the X-API-Key header.

The HeyReach auto-push of any tracked source (person, company page, tracked post or keyword search): the campaign its new leads go to, whether new leads go automatically, its filter rows and whether the worker has paused it. `heyreach` is null when the source has none. An agent's auto-push is `heyreach` on GET /api/v1/agent. Charges nothing.

Authenticated with the X-API-Key header.

Send a source's new leads to a HeyReach campaign automatically. `autoSend` (default true) sends each new lead that passes `filters` once it is enriched, from the moment it is switched on; `pushHistoric: true` also sends the leads already found that pass the filters, once. The filters are the leads tables' Filters rows; a source's leads have no ICP %, signal or engagement count, so those columns are refused (they are the Engagement Agent's ranking). The campaign must exist and be able to take leads. A body of `null`, or `{ "campaignId": null }`, removes the auto-push and drops leads still queued for it. The worker pauses an auto-push when HeyReach rejects the key (`invalid_key`) or the campaign can no longer take leads (`campaign_closed`); saving a campaign starts it again. Only ENRICHED leads are sent; a lead with no LinkedIn profile URL is skipped (`skippedNoLinkedin`); a person is never sent twice to the same campaign (`alreadyInCampaign`); a paused campaign is never resumed, and a finished one is never restarted.

Authenticated with the X-API-Key header.

Creates an asynchronous job to enrich a personal LinkedIn profile. Each matching lead that is successfully enriched consumes one enrichment credit. Leads already enriched for the tracked profile and failed or empty enrichments are not charged. On completion, the job result includes creditsCharged — the number of enriching credits this call actually consumed (0 when every matching lead was already enriched). When saveTrackedProfile=true, tracking is automatic end to end: Cornersight queues a background sync that fetches the profile's recent posts and captures ALL their engagement (reactions and comments) as leads — no separate posts/reactions/comments calls are needed to collect engagement. The sync is QUEUED, not instant: duration depends on current API load and how many posts and engagements the source has, and leads appear progressively, so an empty lead list shortly after tracking does not mean it failed. The response returns a `syncId` when a sync was queued; poll GET /api/v1/{profile|company}/{username}/sync for its stage and progress. RE-TRACKING A SOURCE THAT HAS ALREADY SYNCED DOES NOT RE-SYNC IT: no sync is queued, the response says so with `syncId: null` and `syncNotQueuedReason`, the settings you sent apply from the next scheduled run (POST /api/v1/sources/{id}/sync syncs it now, charged like any sync), and the job enriches only the profile itself. The same full capture then repeats on the daily sync. The reactions and comments endpoints remain available for immediate, targeted single-page pulls. THE `entityUrn` IN THE RESULT IS A LINKEDIN MEMBER ID (`ACoAA…`), and it is exactly the value `fromPerson` and `mentionsPerson` take on POST /api/v1/keyword/track — pass it bare or wrapped as `urn:li:person:<id>`; both are accepted. ⚠️ DO NOT USE THIS ENDPOINT MERELY TO RESOLVE AN ID: without `saveTrackedProfile` it answers 404 for anyone who is not already one of your leads, and WITH it, it tracks them — a full sync, queued and charged. `GET /api/v1/profile/{username}/urn` resolves any public handle for free instead.

Authenticated with the X-API-Key header.

{
  "username": "demo-profile",
  "saveTrackedProfile": false
}

{
  "username": "demo-profile",
  "saveTrackedProfile": true
}

{
  "username": "demo-profile",
  "saveTrackedProfile": true,
  "mode": "posts_only",
  "postsPerSync": 5,
  "confirmSpend": true
}

{
  "username": "demo-profile",
  "saveTrackedProfile": true,
  "firstSyncDays": 30,
  "firstSyncPosts": 20
}

{
  "jobId": "00000000-0000-4000-8000-000000000001"
}

Creates an asynchronous job to enrich a LinkedIn company page. Company enrichment never consumes enriching credits; the completed job result includes creditsCharged: 0. When saveTrackedProfile=true, tracking is automatic end to end: Cornersight queues a background sync that fetches the profile's recent posts and captures ALL their engagement (reactions and comments) as leads — no separate posts/reactions/comments calls are needed to collect engagement. The sync is QUEUED, not instant: duration depends on current API load and how many posts and engagements the source has, and leads appear progressively, so an empty lead list shortly after tracking does not mean it failed. The response returns a `syncId` when a sync was queued; poll GET /api/v1/{profile|company}/{username}/sync for its stage and progress. RE-TRACKING A SOURCE THAT HAS ALREADY SYNCED DOES NOT RE-SYNC IT: no sync is queued, the response says so with `syncId: null` and `syncNotQueuedReason`, the settings you sent apply from the next scheduled run (POST /api/v1/sources/{id}/sync syncs it now, charged like any sync), and the job enriches only the profile itself. The same full capture then repeats on the daily sync. The reactions and comments endpoints remain available for immediate, targeted single-page pulls. On completion the job `result` carries the full firmographic set (industry, employee count and size range, headquarters, description, founded year, follower count, specialties, and a stable company URN) — see the CompanyEnrichmentResult schema. BREAKING (2026-07-18): these fields are now FLAT on `result`, matching profile enrichment; the previous `result.data` envelope and the capital-I `Images` key are gone (`images.logo` now).

Authenticated with the X-API-Key header.

{
  "username": "demo-company",
  "saveTrackedProfile": false
}

{
  "username": "demo-company",
  "saveTrackedProfile": true
}

{
  "username": "instantlyapp",
  "saveTrackedProfile": true,
  "mode": "posts_only",
  "postsPerSync": 5,
  "confirmSpend": true
}

{
  "username": "demo-company",
  "saveTrackedProfile": true,
  "firstSyncPosts": 5
}

{
  "jobId": "00000000-0000-4000-8000-000000000002"
}

Change a tracked personal profile's PER-SYNC CREDIT LIMIT without re-tracking it. THE EDIT THAT COSTS NOTHING: `creditCapPerSync` otherwise reaches a personal profile only through POST /api/v1/enrich/profile, which also runs an enrichment job — and which, on a source that has already synced, queues NO sync: the setting simply applies from the next scheduled run. This route writes the column and nothing else: no sync is queued, no lead is enriched, nothing is charged. ADDRESSED BY THE SAME USERNAME the DELETE on this path takes, so a caller already holds the identifier. An earlier release put this edit on PATCH /api/v1/sources/{id} instead, keyed by source id; that route is REMOVED in favour of these two, which is a breaking change. AN EDIT BINDS FROM THE NEXT SYNC, NEVER THE ONE ALREADY RUNNING. A run reads the source's limit when it starts and holds it for the whole run, so a cap lowered mid-sweep does not cut that sweep short. Whether the run you are looking at actually ended at the limit is reported by GET /api/v1/profile/{username}/sync as `stoppedBy: "credit_cap"`. NOT A KEYWORD SEARCH'S CAP. `creditCap` is a keyword search's per-RUN limit, it lives on keyword_searches, PATCH /api/v1/keyword/{id} writes it and GET /api/v1/sources reports it as `config.creditCap`. The two fields shared the name `creditCap` until this release; they no longer do, and there is no alias — a body still sending `creditCap` here is a 400 carrying `code: "renamed_field"` rather than a 200 that discarded it. AT LEAST ONE SETTING IS REQUIRED: `creditCapPerSync` (which may be null), `mode`, `captureReplies` or `enrichLeads`. Absent means "leave it alone" everywhere else in this API, and a request that changes nothing cannot honestly be answered 200 — so a body naming none of them is a 400, and `null` is the value that REMOVES a limit. `enrichLeads: false` puts the source in RAW MODE (captured and charged as before, never enriched, read with GET /api/v1/leads/raw); like the cap it is an edit that queues nothing, charges nothing and needs no `confirmSpend`, and it applies to leads captured after it. THE MODE CAN BE CHANGED HERE TOO: `mode: "posts_only"` with `postsPerSync` (1-60) makes the source a posts-only watch (new posts only, one credit per new post, no leads), and `mode: "engagers"` turns it back into the engagers sweep. Switching posts-only to engagers can raise the cost, so it is refused 409 `spend_confirmation_required` until the request is re-sent with `confirmSpend: true`; switching to posts-only never needs it. A `mode` change whose current mode cannot be read is a 502 and changes nothing. UNKNOWN FIELDS ARE REFUSED: any other property is a 400 carrying `code: "unknown_field"` and naming it.

Authenticated with the X-API-Key header.

{
  "creditCapPerSync": 250
}

{
  "creditCapPerSync": null
}

{
  "mode": "posts_only",
  "postsPerSync": 5
}

{
  "mode": "engagers",
  "confirmSpend": true
}

{
  "enrichLeads": false
}

{
  "sourceId": "8f1c…",
  "type": "person",
  "username": "demo-profile",
  "creditCapPerSync": 250,
  "previous": {
    "creditCapPerSync": 5000
  }
}

Stop tracking a personal LinkedIn profile. Synchronous. SOFT DELETE, the same contract as untracking a post or a keyword search: the source is DEACTIVATED (`status: "inactive"`), never removed, and nothing it captured is destroyed. It cannot be a row delete — `leads.tracked_profile_id` is `NOT NULL ... ON DELETE CASCADE`, so deleting the source would take every lead it captured with it, which is exactly the data loss this endpoint stopped causing. ACCESS IS A SEPARATE QUESTION FROM STORAGE, and this endpoint answers both differently: nothing is erased, but the leads it captured STOP BEING SERVED — GET /api/v1/leads and GET /api/v1/engagers exclude them from the all-sources view and return `404` for its `profileId`/`username`, exactly as the dashboard, its stat cards and its CSV export do, and the source stops being actionable (POST /api/v1/profile/{username}/push and its `/webhook` and `/icp` routes all `404`). `GET /api/v1/sources?includeInactive=true` enumerates what you used to track; that call lists the source and does not serve its leads. THE LEADS HAVE THEIR OWN OPT-IN: pass the same parameter to the endpoints that serve them — `GET /api/v1/leads?includeInactive=true` and `GET /api/v1/engagers?includeInactive=true` — and the kept leads are returned and this `username`/`profileId` resolves instead of 404ing. It is an API-only opt-in and the default is unchanged, so the dashboard, its stat cards and its CSV export still show nothing for this source. Reactivating does: re-tracking the same username revives the source and its leads are read again. A `404` here means out of scope for that read, never that anything was erased — erasure is a support request, not an API call. Keyword searches are the one kind whose leads stay readable after untracking; see DELETE /api/v1/keyword/{id}. The sweep stops, the source leaves GET /api/v1/sources unless you pass `?includeInactive=true`, and re-tracking the same username REVIVES that source rather than creating a second one. Credits already spent are never refunded. Scoped to the authenticated team; a profile the team does not track returns `404`. Trial profiles cannot be deleted (`403`) — subscribe to a paid plan to manage profiles. WHAT HAPPENS TO WORK THAT IS ALREADY RUNNING — the half this used to leave unsaid, and the half that costs money. A SWEEP ALREADY RUNNING IS STOPPED: the run asks whether its source is still tracked at every checkpoint it passes (before each provider call, before each post is harvested, before each chunk of lead rows) and abandons the run at the first checkpoint after the delete. THAT IS “AT THE NEXT CHECKPOINT”, NOT “INSTANTLY”: a provider call already in flight finishes first, and the check is coalesced behind a short window (one second by default), so expect the stop within moments rather than at the instant the delete returns. If the status read itself fails the run CARRIES ON to the next checkpoint — the control channel fails open on purpose, because abandoning a paying customer's sweep over one timed-out SELECT is the worse error. LEADS ALREADY WRITTEN ARE KEPT, and the run is finalised as `completed` with `stoppedBy: "untracked"` on GET /api/v1/sources/{id}/sync (and the username-keyed /sync routes). ⚠️ THAT VALUE IS NOT IN `lastRun.stoppedBy` on GET /api/v1/sources and never will be: that enum describes how a keyword SWEEP ended and is a closed set. QUEUED ENRICHMENT IS WRITTEN OFF AND NOT CHARGED: enrichment lands minutes to hours after capture, so the backlog is the part of an untracked source that would otherwise go on billing — every lead of this source still `pending` or `processing` is marked `skipped` with the reason `source_untracked` and costs no enriching credits. Re-tracking this source returns exactly those leads to `pending` at the start of its next sync, and returns no other skipped lead with it.

Authenticated with the X-API-Key header.

{
  "ok": true,
  "username": "demo-profile",
  "profileType": "person",
  "untracked": true
}

Change a tracked company page's PER-SYNC CREDIT LIMIT without re-tracking it. THE EDIT THAT COSTS NOTHING: `creditCapPerSync` otherwise reaches a company page only through POST /api/v1/enrich/company, which also runs an enrichment job — and which, on a source that has already synced, queues NO sync: the setting simply applies from the next scheduled run. This route writes the column and nothing else: no sync is queued, no lead is enriched, nothing is charged. ADDRESSED BY THE SAME USERNAME the DELETE on this path takes, so a caller already holds the identifier. An earlier release put this edit on PATCH /api/v1/sources/{id} instead, keyed by source id; that route is REMOVED in favour of these two, which is a breaking change. AN EDIT BINDS FROM THE NEXT SYNC, NEVER THE ONE ALREADY RUNNING. A run reads the source's limit when it starts and holds it for the whole run, so a cap lowered mid-sweep does not cut that sweep short. Whether the run you are looking at actually ended at the limit is reported by GET /api/v1/company/{username}/sync as `stoppedBy: "credit_cap"`. NOT A KEYWORD SEARCH'S CAP. `creditCap` is a keyword search's per-RUN limit, it lives on keyword_searches, PATCH /api/v1/keyword/{id} writes it and GET /api/v1/sources reports it as `config.creditCap`. The two fields shared the name `creditCap` until this release; they no longer do, and there is no alias — a body still sending `creditCap` here is a 400 carrying `code: "renamed_field"` rather than a 200 that discarded it. AT LEAST ONE SETTING IS REQUIRED: `creditCapPerSync` (which may be null), `mode`, `captureReplies` or `enrichLeads`. Absent means "leave it alone" everywhere else in this API, and a request that changes nothing cannot honestly be answered 200 — so a body naming none of them is a 400, and `null` is the value that REMOVES a limit. `enrichLeads: false` puts the source in RAW MODE (captured and charged as before, never enriched, read with GET /api/v1/leads/raw); like the cap it is an edit that queues nothing, charges nothing and needs no `confirmSpend`, and it applies to leads captured after it. THE MODE CAN BE CHANGED HERE TOO: `mode: "posts_only"` with `postsPerSync` (1-60) makes the source a posts-only watch (new posts only, one credit per new post, no leads), and `mode: "engagers"` turns it back into the engagers sweep. Switching posts-only to engagers can raise the cost, so it is refused 409 `spend_confirmation_required` until the request is re-sent with `confirmSpend: true`; switching to posts-only never needs it. A `mode` change whose current mode cannot be read is a 502 and changes nothing. UNKNOWN FIELDS ARE REFUSED: any other property is a 400 carrying `code: "unknown_field"` and naming it.

Authenticated with the X-API-Key header.

{
  "creditCapPerSync": 250
}

{
  "creditCapPerSync": null
}

{
  "mode": "posts_only",
  "postsPerSync": 5
}

{
  "mode": "engagers",
  "confirmSpend": true
}

{
  "enrichLeads": false
}

{
  "sourceId": "8f1c…",
  "type": "company",
  "username": "demo-company",
  "creditCapPerSync": 250,
  "previous": {
    "creditCapPerSync": 5000
  }
}

Stop tracking a LinkedIn company page. Synchronous. SOFT DELETE, the same contract as untracking a profile, a post or a keyword search: the source is DEACTIVATED (`status: "inactive"`), never removed, and nothing it captured is destroyed — `leads.tracked_profile_id` is `NOT NULL ... ON DELETE CASCADE`, so a row delete would take the captured leads with it. ACCESS IS A SEPARATE QUESTION FROM STORAGE, and this endpoint answers both differently: nothing is erased, but the leads it captured STOP BEING SERVED — GET /api/v1/leads and GET /api/v1/engagers exclude them from the all-sources view and return `404` for its `profileId`/`username`, exactly as the dashboard, its stat cards and its CSV export do, and the source stops being actionable (POST /api/v1/company/{username}/push and its `/webhook` and `/icp` routes all `404`). `GET /api/v1/sources?includeInactive=true` enumerates what you used to track; that call lists the source and does not serve its leads. THE LEADS HAVE THEIR OWN OPT-IN: pass the same parameter to the endpoints that serve them — `GET /api/v1/leads?includeInactive=true` and `GET /api/v1/engagers?includeInactive=true` — and the kept leads are returned and this `username`/`profileId` resolves instead of 404ing. It is an API-only opt-in and the default is unchanged, so the dashboard, its stat cards and its CSV export still show nothing for this source. Reactivating does: re-tracking the same username revives the source and its leads are read again. A `404` here means out of scope for that read, never that anything was erased — erasure is a support request, not an API call. Keyword searches are the one kind whose leads stay readable after untracking; see DELETE /api/v1/keyword/{id}. The sweep stops, the source leaves GET /api/v1/sources unless you pass `?includeInactive=true`, and re-tracking the same username REVIVES it. Credits already spent are never refunded. Scoped to the authenticated team; a company page the team does not track returns `404`. Trial profiles cannot be deleted (`403`) — subscribe to a paid plan to manage profiles. WHAT HAPPENS TO WORK THAT IS ALREADY RUNNING — the half this used to leave unsaid, and the half that costs money. A SWEEP ALREADY RUNNING IS STOPPED: the run asks whether its source is still tracked at every checkpoint it passes (before each provider call, before each post is harvested, before each chunk of lead rows) and abandons the run at the first checkpoint after the delete. THAT IS “AT THE NEXT CHECKPOINT”, NOT “INSTANTLY”: a provider call already in flight finishes first, and the check is coalesced behind a short window (one second by default), so expect the stop within moments rather than at the instant the delete returns. If the status read itself fails the run CARRIES ON to the next checkpoint — the control channel fails open on purpose, because abandoning a paying customer's sweep over one timed-out SELECT is the worse error. LEADS ALREADY WRITTEN ARE KEPT, and the run is finalised as `completed` with `stoppedBy: "untracked"` on GET /api/v1/sources/{id}/sync (and the username-keyed /sync routes). ⚠️ THAT VALUE IS NOT IN `lastRun.stoppedBy` on GET /api/v1/sources and never will be: that enum describes how a keyword SWEEP ended and is a closed set. QUEUED ENRICHMENT IS WRITTEN OFF AND NOT CHARGED: enrichment lands minutes to hours after capture, so the backlog is the part of an untracked source that would otherwise go on billing — every lead of this source still `pending` or `processing` is marked `skipped` with the reason `source_untracked` and costs no enriching credits. Re-tracking this source returns exactly those leads to `pending` at the start of its next sync, and returns no other skipped lead with it.

Authenticated with the X-API-Key header.

{
  "ok": true,
  "username": "demo-company",
  "profileType": "company",
  "untracked": true
}

Creates a tracked POST source for the authenticated team and queues its first engagement capture. Synchronous, unlike the engagement job endpoints: the permalink is resolved against LinkedIn before anything is stored, so the call returns either a verified source or an error, never a source that cannot capture. Tracked posts have their own trial ceiling, separate from tracked profiles — a trial team may hold both. Re-tracking a post the team already has never creates a second source: an active source keeps its URL and applies any named captureReplies or creditCapPerSync setting without another capture, while an untracked source is reactivated — which queues a fresh capture and therefore charges. The status is `201` either way. A re-track of a post that has ALREADY SYNCED queues nothing and says so — `syncId: null` beside `syncNotQueuedReason` (POST /api/v1/sources/{id}/sync syncs it now) — and otherwise the body does not distinguish a duplicate from a genuine create, so re-read GET /api/v1/sources if you need to know which happened. (POST /api/v1/keyword/track, whose identity is its keywords rather than a URN, answers the same case with `200` and `resumed: true`.) WHAT YOU CAN DO WITH A TRACKED POST FROM THIS API: it is listed by GET /api/v1/sources (filter ?type=post), its engagers are returned by GET /api/v1/leads like any other source's, and it is removed by DELETE /api/v1/post/{urn}. ITS SYNC STATUS, WEBHOOK AND ICP CONFIG ARE AT /api/v1/sources/{id}/sync, /webhook and /icp — addressed by the SOURCE ID this response's source carries and GET /api/v1/sources lists, not by the URN. Use the `syncId` above with GET /api/v1/sources/{id}/sync (the source id, not the syncId) to follow the capture you just queued. The per-kind routes cannot take a post: /api/v1/{profile|company}/{username}/sync, /webhook and /icp are keyed by a LinkedIn username and a post's identifier is an activity URN, which is why these were dashboard-only until the source-id family existed. Nothing about the post source was ever the limitation — it syncs, delivers to a webhook and is ICP-filtered exactly like any other source. LARGE POSTS STOP AT THE PROVIDER'S CEILING, ABOUT 1,100 PEOPLE. Measured 29 September 2026 on a public company post declaring 3,490 reactions: the data provider served about 1,100 reactors (22 pages of ~50) and then only empty pages, while every page still declared 3,490. No paging, retry or `creditCapPerSync` gets the rest — it is not obtainable from the provider. Its sync says so instead of claiming it collected everything: GET /api/v1/sources/{id}/sync ends with `capture.stoppedBy: "provider_limit"` (and the same at the top level), and `capture.coverage` gives the declared and captured counts side by side. A post under the ceiling captures in full and still ends `exhausted`. `400` means the URL can never work and the message says what to paste instead. `503` with code `post_resolve_failed` means the post could not be verified right now and the request is worth retrying; no source is created in either case.

Authenticated with the X-API-Key header.

{
  "postUrl": "https://www.linkedin.com/posts/some-person_a-post-slug-activity-0000000000000000000-AbCd"
}

Stop tracking a post and stop capturing its engagement. The delete half of the pair with POST /api/v1/post/track. Synchronous. SOFT DELETE, like untracking a profile: the source is deactivated, never removed, because leads reference it and a row delete would cascade the captured leads away with it. The post stops syncing and leaves the tracked-source list. Its captured leads are RETAINED in your account but stop being SERVED: GET /api/v1/leads excludes an untracked post's leads from the all-sources view and returns 404 for its id BY DEFAULT, which is what the dashboard shows too. `GET /api/v1/sources?includeInactive=true` still lists the post, with `status: "inactive"` — and `GET /api/v1/leads?includeInactive=true` / `GET /api/v1/engagers?includeInactive=true` read the kept leads back and make that id resolve. That opt-in exists on the API only; the dashboard has no equivalent switch, so its own view is unchanged. Keyword searches are the one kind whose leads stay readable after untracking — see DELETE /api/v1/keyword/{id}. Untracking a post that is already untracked returns `404`. Identify the post by the URN that GET /api/v1/sources returns for it (`urn:li:activity:…` or `urn:li:ugcPost:…`) — the same value POST /api/v1/post/track echoes back as `postUrn`. The colons are legal in a path segment, so both the raw and percent-encoded forms work. A tracked post's sync status, webhook config and ICP config are reached by its SOURCE ID at /api/v1/sources/{id}/sync, /webhook and /icp — not by this URN; see POST /api/v1/post/track. `403` for a post tracked during a free trial: trial sources cannot be deleted on any surface, the dashboard included, until the team subscribes. WHAT HAPPENS TO WORK THAT IS ALREADY RUNNING — the half this used to leave unsaid, and the half that costs money. A SWEEP ALREADY RUNNING IS STOPPED: the run asks whether its source is still tracked at every checkpoint it passes (before each provider call, before each post is harvested, before each chunk of lead rows) and abandons the run at the first checkpoint after the delete. THAT IS “AT THE NEXT CHECKPOINT”, NOT “INSTANTLY”: a provider call already in flight finishes first, and the check is coalesced behind a short window (one second by default), so expect the stop within moments rather than at the instant the delete returns. If the status read itself fails the run CARRIES ON to the next checkpoint — the control channel fails open on purpose, because abandoning a paying customer's sweep over one timed-out SELECT is the worse error. LEADS ALREADY WRITTEN ARE KEPT, and the run is finalised as `completed` with `stoppedBy: "untracked"` on GET /api/v1/sources/{id}/sync (and the username-keyed /sync routes). ⚠️ THAT VALUE IS NOT IN `lastRun.stoppedBy` on GET /api/v1/sources and never will be: that enum describes how a keyword SWEEP ended and is a closed set. QUEUED ENRICHMENT IS WRITTEN OFF AND NOT CHARGED: enrichment lands minutes to hours after capture, so the backlog is the part of an untracked source that would otherwise go on billing — every lead of this source still `pending` or `processing` is marked `skipped` with the reason `source_untracked` and costs no enriching credits. Re-tracking this source returns exactly those leads to `pending` at the start of its next sync, and returns no other skipped lead with it.

Authenticated with the X-API-Key header.

{
  "ok": true,
  "username": "urn:li:activity:7123456789012345678",
  "profileType": "post",
  "untracked": true
}

PRICES A KEYWORD SEARCH WITHOUT CREATING IT — the call to make BEFORE POST /api/v1/keyword/track. WHY IT EXISTS. The 409 `spend_confirmation_required` already carries the estimate, and it is a workable way to obtain one — but it makes "show me the cost" AN ERROR PATH. A CLI has to print a refusal in order to answer a question, and an agent written the ordinary way treats every non-2xx as a failure and never reads the body: the MCP layer collapses a failed tool result to `{ statusCode, error }`, so the numbers in that 409 reach no agent at all. This answers 200 with the same object, so they do. The 409 is unchanged and remains the ENFORCEMENT; this is the intended first call. IT CREATES NOTHING, RESUMES NOTHING AND CHARGES NOTHING. No source row, no search row, no status change on a search you already have, no queued sweep, no credit. It performs two reads and returns. THE SAME BODY AS THE CREATE, WITH THE SAME 400s. Every field POST /api/v1/keyword/track accepts is accepted here and validated by the same code in the same order, so a body this endpoint prices is a body that endpoint would accept. An estimate that accepted what the create refuses would be answering a question about a search that cannot exist. THE CONTRACT'S TWO GATES DO NOT APPLY HERE, deliberately. `scope_required` and `spend_confirmation_required` are about authorising a recurring charge, and this endpoint creates none — so the four scope fields are OPTIONAL here even after the cut-over, and `confirmSpend` is accepted (validated for shape, as everywhere) and does nothing. Requiring them would mean choosing the scope in order to be told what the scope costs, which is the question. The caps are still RESOLVED exactly as the create resolves them — sent wins, omitted inherits from the live search, else the create-time default — which is what makes this `estimatedDailyMax` and the subsequent 201's the same number. RESUMED. `resumed: true` means these terms already name a search this team has (ACTIVE or one you DELETED), so the create that follows would return THAT search, apply the settings you named and leave the rest alone — and, if it had been deleted, track it again and queue a charging sweep within seconds. `previous` then carries that search's CURRENT caps beside the requested ones, under the same key and with the same meaning the 409 gives it. THE FORMULA behind `estimatedDailyMax` and `daysToExhaustAtCap` is written out once, on POST /api/v1/keyword/track. Both keys are OMITTED here, never null and never 0, when there is no honest number — test for the KEY.

Authenticated with the X-API-Key header.

{
  "keywords": [
    "AI agents"
  ]
}

{
  "keywords": [
    "AI agents",
    "LLM evals"
  ],
  "datePosted": "PAST_WEEK",
  "captureMode": "breadth",
  "creditCap": 500
}

Creates a KEYWORD SEARCH: a recurring sweep that finds LinkedIn posts by ONE OR MORE keywords (up to ten), optionally filters them with your own AI model against a criterion you write, and captures the engagers of the survivors as leads — or, with `capturePostAuthors: true`, the person who WROTE each surviving post as an `Author` lead, beside the engagers or (`captureEngagers: false`) instead of them. An author is charged like an engager: one credit per NEW person for the search, repeats free, company-page authors skipped and never charged. It becomes a tracked source like a profile or a post — listed by GET /api/v1/sources with type `keyword`, its leads returned by GET /api/v1/leads. SYNCHRONOUS, and unlike POST /api/v1/post/track there is nothing to verify: a post must be resolved against LinkedIn before it can be stored, but a keyword search performs no provider call at creation — the sweep happens later. This returns the created source, not a jobId. The first sweep is queued immediately; poll its progress with GET /api/v1/{profile|company}/{username}/sync's sibling on the dashboard, or simply read the leads as they arrive. THE AI KEY IS NOT ACCEPTED BY THIS ENDPOINT and cannot be supplied through this API at all. Save it once in the dashboard's AI filtering panel, on Keyword Engagement — the same panel that sets the provider and prompt. It is held in an encrypted vault, one key per provider per team, and never returned by any endpoint; the panel lists which providers your team has a key for so you can confirm one is stored. `aiProvider` only names WHICH stored key to use. A search whose provider has no saved key fails at run time with a clear reason rather than at creation. THE AI FILTER RUNS ON YOUR KEY AND IS BILLED BY YOUR PROVIDER, NOT BY CORNERSIGHT, and nothing you set here caps it except the run itself: every post a run scans is sent to your model — up to 2,000 posts in each run, 10 to a call (about 200 calls), or one call per post when the model's batch answer cannot be read — and a post already judged under the same prompt is never sent again. `creditCap` bounds Cornersight credits only. EACH TERM IS ONE PROVIDER CALL per run, merged and deduplicated by post URN. The run's scan — at most 2,000 posts, an internal safety bound and not a setting — is shared across the terms and allocated round-robin, so one high-volume term cannot crowd out the others, and a term that exhausts early yields its share. Keyword searches have their own trial ceiling, separate from profiles and posts. Remove one with DELETE /api/v1/keyword/{id}. ⚠️ THE CUT-OVER IS SCHEDULED FOR 2026-11-01, AND THIS IS THE NOTICE OF IT. UNTIL 2026-11-01 an old-style create — one that omits the three scope fields and `confirmSpend` — still returns 201/200 and carries a `deprecations` entry naming exactly what to add. FROM 2026-11-01 the same request is refused: a missing scope field is `400` `scope_required` naming the field, and a scope that is stated but not confirmed is `409` `spend_confirmation_required` — the same refusal a request pinned to `contractVersion: "2026-11-01"` already gets today, which is how you test the new behaviour before the date. THE EXACT CHANGE IS FOUR KEYS: add "creditCap": 100, "captureMode": "depth", "datePosted": "PAST_WEEK" and "confirmSpend": true to the request body. Those three values are what the dashboard's "Search scope" step pre-fills, offered so you can copy them DELIBERATELY — they are NOT server-side defaults and nothing is chosen for you, so send the caps you actually want, and send `confirmSpend` only once the person has heard the daily figure. THE VERSION STRING AND THE CUT-OVER DATE ARE THE SAME DAY, which they did not have to be: the version is what you PIN, the date is what happens to you if you do not. IT RUNS EVERY DAY, AND CHARGES EVERY DAY. This is not a one-off search: once created, the sweep repeats roughly every 24 hours until you untrack it, and `creditCap` is PER RUN, not a total for the life of the search. The first sweep starts within seconds of creation, not a day later, and the daily cadence runs from there. CREATED, OR THE ONE YOU ALREADY HAVE: a keyword search's identity is its joined terms, so creating one whose keywords match a search this team already has — whether that search is ACTIVE or one you DELETED — returns THAT search instead of making a second one. The response is 200 with `resumed: true` rather than 201, and `seenPosts` says how many posts it has already swept and will therefore SKIP; a genuine create returns 201 with `resumed: false` and `seenPosts: 0`. THE SETTINGS YOU SEND ARE APPLIED TO THAT SEARCH AND THE ONES YOU OMIT ARE LEFT AS THEY ARE, so a bare `{"keywords": [...]}` returns it unchanged rather than resetting its name, its AI filter and its caps to the defaults; send an explicit `null` to clear a field. For the same reason `name` and `aiProvider` in the response are the search's CURRENT values, not an echo of what you sent. RESUMING A DELETED SEARCH ALSO TRACKS IT AGAIN and queues a sweep within seconds, which charges — if you did not mean to bring it back, untrack it again with DELETE /api/v1/keyword/{id}. A `creditCap` of 2000 means up to 2000 enriching credits EVERY DAY, not 2000 once. Set the caps to what one day may cost, and remove the search with DELETE /api/v1/keyword/{id} when you no longer want it running. Each run sweeps only posts it has not captured before — a post captured once is never re-swept, so successive runs return new people rather than re-charging for the same ones. ONE LIMIT: `creditCap`. It is the only limit you set on a search that captures people, and a run ends when it has spent it, when the provider has no new posts, or on the walk's safety bound (20 provider pages per term, and at most 2,000 posts scanned in one run) — never because a post count was reached. A credit is charged per NEW PERSON for this source, not per post or repeat engagement, so one post with 300 distinct new people can cost up to 300 credits. A `posts_only` search captures no people and is bounded by `postsPerSync` new posts or `creditCap` credits, whichever is lower. The retired per-run post limit, `postBudget`, is accepted and IGNORED if you still send it (since 30 September 2026), and the reply lists it in `ignoredFields`. WHAT ONE DAY CAN COST, AS A FORMULA — THE ONE PLACE IT IS WRITTEN DOWN. Every surface that quotes a spend estimate computes it the same way, from one shared function: `estimatedDailyMax = creditCap` for a search that captures people — with or without post authors — and `estimatedDailyMax = min(postsPerSync, creditCap)` for a `posts_only` search, which buys at most `postsPerSync` new posts a day at one credit each. POST /api/v1/keyword/estimate, this endpoint's 201/200 and its 409, and PATCH /api/v1/keyword/{id} all quote that one figure. The fields that look like they belong in it are deliberately not in it. `captureMode` is not, because `depth` and `breadth` only choose how the cap is SPREAD across a run's posts, and both stop at the same cap. `maxEngagementsPerPost` is not, and that is the one that surprises: the per-post ceiling times the posts a run reaches is often what a run actually spends, but it is not a limit we can promise — a post whose engagement counts the provider did not return is allocated the whole remaining cap, so a run with a low per-post ceiling can still spend the full `creditCap`. The estimate is therefore the most a day can cost, never the least: an estimate that came in under what you are charged would be worse than no estimate at all. When `creditCap` is absent, zero, negative or not a whole number there is NO estimate, rather than an estimate of zero. Against your team's remaining enriching-credit balance the same calculation gives `daysToExhaustAtCap = floor(balance / estimatedDailyMax)`: WHOLE days at that rate, so a balance of 250 against a cap of 100 is 2 and not 3, and any balance below the cap is 0 — the very first sweep is the one that gets cut short. With no usable cap there is no rate to divide by, so `daysToExhaustAtCap` is absent too: never zero, never infinite. BOTH FIGURES ARE RETURNED, not merely documented: this endpoint carries `estimatedDailyMax` and `daysToExhaustAtCap` beside the created search on the 201 AND on the 200 resume, computed from the caps that will actually bind the next run, and GET /api/v1/sources carries the same two inside a keyword source's `config`, so a search created on any surface can be read back. Each is OMITTED rather than zeroed whenever it has no honest value — test for the key, not for a number. WHY A RUN STOPPED, AND WHAT IT DID, is reported by GET /api/v1/sources on the source's `lastRun` object, which carries seventeen fields answering four questions. WHEN AND WHY IT ENDED: `at`, `stoppedBy` (the category), `reason` (the sentence behind it — for `ai_error` a sentence Cornersight owns, not the provider's raw response) and `aiErrorCode`, present only on an `ai_error`, which is the stable token to branch on: `model_not_found`, `invalid_key`, `rate_limited`, `out_of_credit` (the provider account behind the key has no credit: add credit with the provider, do not rotate the key) or `provider_error` — and `provider_error` is the provider's own outage, never a reason to tell someone to rotate a working key. WHAT THE PROVIDER RETURNED BUT CORNERSIGHT COULD NOT SAFELY CAPTURE: `providerPageLimitReached` records whether the 20-page safety bound ended a term before exhaustion was proven; `providerRowsDropped` counts provider result rows skipped because they lacked a capturable activity URN; the walk continues past those pages instead of ending early. It is rows across terms/pages, not necessarily unique posts, and is omitted for unmeasured runs. HOW MUCH IT LOOKED AT: `postsScanned` → `postsKept` is the AI filter's before/after, while `postsHarvested` is how far the run actually REACHED, which can be far below `postsKept` when a cap stopped it early. AND, ON A SEARCH BUILT FROM AN `expression`, `discardedByExpression` — and `postsFilteredOut`, the same number under its older name — is how many harvested posts its AND/NOT terms discarded, so the run summary reads searched `postsScanned`, discarded `discardedByExpression`, kept `postsKept`. Both are OMITTED for a search without an expression and PRESENT AND 0 when one discarded nothing, which is the distinction between an expression to rewrite (`postsHarvested: 0` beside `discardedByExpression: 47`) and a search that simply found nothing (the keys absent). A discarded post IS counted in `postsScanned` and NOT in `postsKept`, and GET /api/v1/sources/{id}/kept-posts?include=swept names each one with the clause it failed. WHAT BECAME OF THE PEOPLE, which is how a run that yielded almost nothing is diagnosed: `engagersSeen` is the denominator, `engagersDropped` counts engagers seen but not turned into leads — since 2026-09-08 that no longer means 'had no public handle', because those are now captured under their member URN; what is left is an engager with no identity at all, plus organisation pages, which were never leads, `engagersDuplicate` includes already-stored rows and free repeat engagements, `repeatEngagements` counts the latter subset, `leadsWritten` is inserted engagement rows, and `creditsSpent` counts newly charged people under the name that says what it cost — one credit is one newly chargeable person per source. The five capture counters are OMITTED, never zeroed, for runs predating them. Each field is documented on GET /api/v1/sources. `lastRun` is `null` for person, company and post sources (they have no sweep of their own) and is ALWAYS an object for a keyword search - with null members until the first run finishes, so "not a keyword source" stays distinguishable from "has not run yet". `stoppedBy` is one of `credits` (reached creditCap - the real spend bound; on a `posts_only` search only when creditCap was below postsPerSync), `post_limit` (a `posts_only` search bought its postsPerSync posts for the day - raise postsPerSync, not creditCap, for more), `exhausted` (the provider walk ended without a capture cap; `providerPageLimitReached: true` proves the walk's safety bound fired - 20 pages per term, or 2,000 posts in the run; false only says it did not, because an all-seen RELEVANCE page can also stop before later unseen posts), `error` (the sweep itself failed), `ai_error` (the team's own AI credential failed - the search is otherwise fine) or `capture_empty` (the sweep harvested real posts and every engager fetch answered and returned NOBODY - a CAPTURE failure, never a narrow search; a run that harvested nothing is a clean `exhausted` instead) - and `budget` only on a run from before 30 September 2026, when a per-run post limit existed that has since been retired. The difference that matters most: `credits` and `post_limit` mean a capture cap ended the run; `exhausted` means the provider walk ended without one. `providerPageLimitReached: true` proves the page bound fired; false only says it did not, because an all-seen RELEVANCE page can also stop before later unseen posts. WHEN AN EDIT TAKES EFFECT: FROM THE NEXT RUN, NEVER THE ONE ALREADY RUNNING. A sweep reads the search's configuration ONCE, when it starts, and holds it for the whole run - so settings changed while a sweep is in flight do not re-bind it, and a run that began on the old budgets finishes on them. A change made BEFORE the sweep starts does bind that run, including one made after its job was queued: the worker reads the configuration when it picks the job up, not when the job was created. That is why a run's counts can look like a cap overrun and not be one - read `lastRun.config` on GET /api/v1/sources, which is the snapshot of what THAT run was bound by, against `config`, which is what the search is set to now and what its next run will use. `lastRun.config` is omitted for runs that predate it and is never back-filled from the current settings. ON A TRIAL a team may hold at most 2 keyword searches, and each captures at most 250 leads.

Authenticated with the X-API-Key header.

{
  "keywords": [
    "AI agents"
  ]
}

{
  "datePosted": "PAST_WEEK",
  "sort": "DATE_POSTED",
  "aiProvider": "openai",
  "aiModel": "gpt-4o-mini",
  "aiPrompt": "Keep posts where the author is hiring. Reject recruiters advertising services.",
  "creditCap": 100,
  "keywords": [
    "hiring engineers",
    "we are hiring",
    "join our team"
  ]
}

Change a live keyword search's settings — its caps, its scope, its AI filter and its provider-side targeting — without re-creating it. WHY IT EXISTS. Until now the only way to re-cap a live search from outside the dashboard was to call POST /api/v1/keyword/track again with the same keywords, which RESUMES the search and applies whatever settings the call carries. That works, but it makes "raise the cap on my live search" and "create a search" the same request. This is the request that says which. Partial update: only the fields present in the body change, an omitted one is left exactly as it is, and an explicit `null` clears it — to null on a nullable column, and to the create-time default on a NOT NULL one (`creditCap` 100, `captureMode` depth, `sort` DATE_POSTED, `datePosted` PAST_WEEK), which is the only coherent reading of "clear" for those. ⚠️ A CHANGE THAT RAISES WHAT ONE DAY CAN COST NEEDS `"confirmSpend": true` — that figure is `estimatedDailyMax`: `creditCap` on a search that captures people, `min(postsPerSync, creditCap)` on a `posts_only` search, so raising `creditCap` alone on a `posts_only` search whose `postsPerSync` is below it needs no confirmation — and is otherwise a `409` `spend_confirmation_required` whose message names the search and the new daily cap, carrying `previous` (the caps the search holds now), the resulting `creditCap`/`captureMode`/`datePosted`, `raised` (which setting pushed the figure up: `creditCap`, or `postsPerSync`), `estimatedDailyMax`, `remainingBalance` and `daysToExhaustAtCap` — the same numbers the dashboard puts above its Confirm button, and the same 409 shape POST /api/v1/keyword/track returns. NOTHING WAS CHANGED; re-send the identical request with `"confirmSpend": true` to authorise it, and do not shrink the cap to get past the refusal. LOWERING a cap, leaving it alone, or changing anything else needs no confirmation, because none of those increases what a day can cost. The rule is NOT tied to the spend contract's cut-over date: it applies today, on this endpoint and on a resume alike. WHEN IT TAKES EFFECT: FROM THE NEXT RUN. A sweep reads its settings once, when it starts, so a run already in flight finishes on the caps it began with — read `lastRun.config` on GET /api/v1/sources for what the last run was actually bound by, and `config` for what the next one will use. An edit made before the sweep starts, including after its job is queued, does bind that run. `keywords` CANNOT BE CHANGED HERE and sending it is a `400`, not a silent drop: a search's terms are its identity, and its seen-set is keyed to the SEARCH rather than to a term, so new terms would inherit the old ones' swept posts and sweep a smaller universe than they appear to. Create a search with the new terms and untrack this one. Identify the search by the SOURCE `id` GET /api/v1/sources returns — the same id DELETE /api/v1/keyword/{id} takes and POST /api/v1/keyword/track echoes back — never by its keyword text, which is what `username` shows. Mirrored as the CLI's `keyword-update` and MCP's `update_keyword`. UNKNOWN FIELDS ARE REFUSED: a property not listed here is a 400 carrying `code: "unknown_field"` and naming the offending field, rather than a 200 that silently dropped it.

Authenticated with the X-API-Key header.

Stop a keyword search and stop capturing from it. The delete half of the pair with POST /api/v1/keyword/track. Synchronous. SOFT DELETE, like untracking a profile or a post: the source is deactivated, never removed, because leads reference it and a row delete would cascade the captured leads away. Sweeping stops and the search leaves the tracked-source list; the leads it already captured are kept and stay listed by GET /api/v1/leads. REACH THEM AFTERWARDS with `GET /api/v1/leads?sourceKind=keyword`, which spans stopped searches as well as running ones, or put the search back in the list with `GET /api/v1/sources?includeInactive=true` — its id still works as a `profileId`. Without one of those two the search is no longer enumerable, and its leads are reachable only by an id you recorded before untracking. Untracking one that is already untracked returns `404` with `code: "keyword_delete_already_stopped"` and `error: "That search is already stopped."` — DISTINGUISHABLE from the `404` for a search that never existed, which carries no code. The status is the same for both on purpose (untracking twice behaves as it did when the row was hard-deleted), but for a keyword search the two are not the same fact: an already-stopped search is still listed by `GET /api/v1/sources?includeInactive=true`, its id still resolves on `GET /api/v1/leads` and `GET /api/v1/engagers`, and its leads are still served. BRANCH ON `code`, never on the prose. It is the same value the dashboard has emitted for this case for months. Identify it by the source `id` GET /api/v1/sources returns — the same value POST /api/v1/keyword/track echoes back as `id`. Not by the keyword text. `403` for a search created during a free trial: trial sources cannot be deleted on any surface, the dashboard included, until the team subscribes. Stops the daily sweep and with it the daily charge. Leads already captured are kept. The `id` is the SOURCE id — the `id` field of the object POST /api/v1/keyword/track returned, and the one GET /api/v1/sources lists — not a keyword string. WHAT HAPPENS TO WORK THAT IS ALREADY RUNNING — the half this used to leave unsaid, and the half that costs money. A SWEEP ALREADY RUNNING IS STOPPED: the run asks whether its source is still tracked at every checkpoint it passes (before each provider call, before each post is harvested, before each chunk of lead rows) and abandons the run at the first checkpoint after the delete. THAT IS “AT THE NEXT CHECKPOINT”, NOT “INSTANTLY”: a provider call already in flight finishes first, and the check is coalesced behind a short window (one second by default), so expect the stop within moments rather than at the instant the delete returns. If the status read itself fails the run CARRIES ON to the next checkpoint — the control channel fails open on purpose, because abandoning a paying customer's sweep over one timed-out SELECT is the worse error. LEADS ALREADY WRITTEN ARE KEPT, and the run is finalised as `completed` with `stoppedBy: "untracked"` on GET /api/v1/sources/{id}/sync (and the username-keyed /sync routes). ⚠️ THAT VALUE IS NOT IN `lastRun.stoppedBy` on GET /api/v1/sources and never will be: that enum describes how a keyword SWEEP ended and is a closed set. QUEUED ENRICHMENT IS WRITTEN OFF AND NOT CHARGED: enrichment lands minutes to hours after capture, so the backlog is the part of an untracked source that would otherwise go on billing — every lead of this source still `pending` or `processing` is marked `skipped` with the reason `source_untracked` and costs no enriching credits. Re-tracking this source returns exactly those leads to `pending` at the start of its next sync, and returns no other skipped lead with it.

Authenticated with the X-API-Key header.

Progress of the background capture sync for a tracked personal LinkedIn profile. Tracking (saveTrackedProfile=true) queues a staged sync — collecting_posts → collecting_engagements → enriching → completed — and the jobId returned by the enrichment endpoints covers ONLY the profile enrichment, not this sync. Poll this to tell queued / in progress / complete-with-0-leads / failed apart, and stop when `isFinal` is true. THE LIFECYCLE INCLUDES ENRICHMENT, AND SO DOES `isFinal`: capture writes the engagement records, then new people for this source are enriched with firmographics for one credit each; their repeat engagement rows are free, and that second half normally runs on well after the capture run itself has ended. `state` therefore stays `enriching` and `isFinal` stays false while leads are still being enriched and billed — read `enrichment` for the pending / completed / failed / skipped breakdown, and `capture` when all you need to know is that collection finished. Duration is not fixed: the sync is queued, and how long it takes depends on current API load and how many posts and engagements the source has. Leads appear progressively while it runs.

Authenticated with the X-API-Key header.

Progress of the background capture sync for a tracked LinkedIn company page. Tracking (saveTrackedProfile=true) queues a staged sync — collecting_posts → collecting_engagements → enriching → completed — and the jobId returned by the enrichment endpoints covers ONLY the profile enrichment, not this sync. Poll this to tell queued / in progress / complete-with-0-leads / failed apart, and stop when `isFinal` is true. THE LIFECYCLE INCLUDES ENRICHMENT, AND SO DOES `isFinal`: capture writes the engagement records, then new people for this source are enriched with firmographics for one credit each; their repeat engagement rows are free, and that second half normally runs on well after the capture run itself has ended. `state` therefore stays `enriching` and `isFinal` stays false while leads are still being enriched and billed — read `enrichment` for the pending / completed / failed / skipped breakdown, and `capture` when all you need to know is that collection finished. Duration is not fixed: the sync is queued, and how long it takes depends on current API load and how many posts and engagements the source has. Leads appear progressively while it runs.

Authenticated with the X-API-Key header.

Check a tracked KEYWORD SEARCH's background capture sweep: stage, progress counts, and whether it has finished. Addressed by SOURCE ID, not by keyword text: a keyword search's identifier in GET /api/v1/sources is `id`, while its `username` there is the free-text terms it searches for. A keyword sweep writes a sync_jobs row exactly as a profile sync does, so the state, phase, counters and lead totals here mean the same thing for it as for any other source. THE LIFECYCLE INCLUDES ENRICHMENT, AND SO DOES `isFinal`: capture writes the engagement records, then new people for this source are enriched with firmographics for one credit each; their repeat engagement rows are free, and that second half normally runs on well after the capture run itself has ended. `state` therefore stays `enriching` and `isFinal` stays false while leads are still being enriched and billed — read `enrichment` for the pending / completed / failed / skipped breakdown, and `capture` when all you need to know is that collection finished.

Authenticated with the X-API-Key header.

Check ANY tracked source's background capture sync: stage, progress counts, and whether it has finished. ADDRESSED BY SOURCE ID, AND IT WORKS FOR EVERY KIND OF SOURCE — a person, a company page, a TRACKED POST or a KEYWORD SEARCH. The per-kind routes are keyed by whatever identifier that kind happens to have (/api/v1/{profile|company}/{username}/... by LinkedIn handle, /api/v1/keyword/{id}/... by source id), which is why a tracked post — whose identifier is an activity URN — had no route at all. It was never the SETTING that was missing: a tracked post is a tracked_profiles row like any other, its webhook fires through the same path, its leads are scored against the same ICP rules, and POST /api/v1/post/track has always returned a `syncId` from a real sync job. Only the addressing was. THIS IS HOW YOU FOLLOW A TRACKED POST. POST /api/v1/post/track answers with a `syncId` — a real sync_jobs row, queued the same way a profile's first sync is — and until this route existed there was nothing to hand that id to, so "is my post capturing?" was unanswerable from the API. THE BODY IS THE SAME LIFECYCLE OBJECT the per-kind /sync routes return, field for field, because it is the same code: what differs between the routes is how you addressed the source and the identity fields you get back, never what "finished" means. THE LIFECYCLE INCLUDES ENRICHMENT, AND SO DOES `isFinal`: capture writes the engagement records, then new people for this source are enriched with firmographics for one credit each; their repeat engagement rows are free, and that second half normally runs on well after the capture itself has ended. `state` therefore stays `enriching` and `isFinal` stays false while leads are still being enriched and billed — read `enrichment` for the pending / completed / failed / skipped breakdown, and `capture` when all you need to know is that collection finished.

Authenticated with the X-API-Key header.

QUEUE A CAPTURE SYNC OF A TRACKED PERSON, COMPANY PAGE OR TRACKED POST NOW, instead of waiting for its next scheduled sync. RE-TRACKING DOES NOT RE-SYNC: POST /api/v1/enrich/profile or /enrich/company with `saveTrackedProfile: true`, and POST /api/v1/post/track, on a source that has already synced apply the settings sent and queue nothing (`syncId: null` + `syncNotQueuedReason`). This is the sync. **Cost.** Charged like any sync of that source: one enriching credit per NEW person for the source, repeat engagement free, bounded by the source's `creditCapPerSync` when it has one. There is no separate price; a second sync in a day costs what the next day's scheduled sync would. **Never stacked.** When a sync of the source is already queued, running or paused for enriching credits, nothing new is queued: the answer is `200` with `queued: false`, that job's `syncId` and `status`, and a `message`. Otherwise it is `202` with `queued: true` and the new job's `syncId`. Follow either with GET /api/v1/sources/{id}/sync. **Schedule.** The source's next scheduled sync moves to at least 24 hours from now, so the daily sync does not run it again straight after; a `nextSyncAt` already further out is left as it is. **Keyword searches are refused** with `400` and code `keyword_search_not_syncable`: a keyword search runs on its own daily schedule and each run may spend its `creditCap`, so an extra run would spend it twice in one day. There is no run-now route for a keyword search; follow its runs with GET /api/v1/keyword/{id}/sync, change it with PATCH /api/v1/keyword/{id}, and restart a stopped one with POST /api/v1/keyword/track.

Authenticated with the X-API-Key header.

Read the webhook configuration — delivery URL and flags — of any tracked source. ADDRESSED BY SOURCE ID, AND IT WORKS FOR EVERY KIND OF SOURCE — a person, a company page, a TRACKED POST or a KEYWORD SEARCH. The per-kind routes are keyed by whatever identifier that kind happens to have (/api/v1/{profile|company}/{username}/... by LinkedIn handle, /api/v1/keyword/{id}/... by source id), which is why a tracked post — whose identifier is an activity URN — had no route at all. It was never the SETTING that was missing: a tracked post is a tracked_profiles row like any other, its webhook fires through the same path, its leads are scored against the same ICP rules, and POST /api/v1/post/track has always returned a `syncId` from a real sync job. Only the addressing was. Same column, same delivery path and same four flags for every kind: a tracked post's and a keyword search's `lead.detected` have always fired, and only reading and setting them from outside the dashboard is new. FOR A TRACKED POST, `webhookUrl`, `icpOnly` and `autoSend` apply to its `lead.detected` exactly as for any source (`autoSend: false` holds its leads for POST /api/v1/sources/{id}/push); `syncEvents` does not, because no sync lifecycle event is ever sent for a post, so the PUT refuses `syncEvents: true` on one.

Authenticated with the X-API-Key header.

Configure how leads are delivered OUT of Cornersight for ANY tracked source. ADDRESSED BY SOURCE ID, AND IT WORKS FOR EVERY KIND OF SOURCE — a person, a company page, a TRACKED POST or a KEYWORD SEARCH. The per-kind routes are keyed by whatever identifier that kind happens to have (/api/v1/{profile|company}/{username}/... by LinkedIn handle, /api/v1/keyword/{id}/... by source id), which is why a tracked post — whose identifier is an activity URN — had no route at all. It was never the SETTING that was missing: a tracked post is a tracked_profiles row like any other, its webhook fires through the same path, its leads are scored against the same ICP rules, and POST /api/v1/post/track has always returned a `syncId` from a real sync job. Only the addressing was. PARTIAL UPDATE: only the fields present in the body change, so a flag can be flipped without restating the URL; a body with none of them is a 400 rather than a silent no-op. EXPLICIT `false` IS A VALUE — `autoSend: false` puts the source into deliver-only-on-explicit-push mode, which is what POST /api/v1/{profile|company}/{username}/push, /api/v1/keyword/{id}/push and, for any kind (the only push a tracked post has), /api/v1/sources/{id}/push then act on. `webhookUrl` of `""` or `null` CLEARS delivery, and turns `syncEvents` off with it because there is nowhere left to deliver — asking for `syncEvents: true` with no URL is a 400 instead. The URL passes the same guard the delivery path applies, so a URL that saves is always one that can fire. FOR A TRACKED POST, `webhookUrl`, `icpOnly` and `autoSend` apply to its `lead.detected` exactly as for any source (`autoSend: false` holds its leads for POST /api/v1/sources/{id}/push), while `syncEvents: true` is a 400 with `code: "not_supported_for_post"`: no sync lifecycle event is ever sent for a post. SAVING A URL DOES NOT DELIVER HISTORY; the push endpoints do that. UNKNOWN FIELDS ARE REFUSED: a property not listed here is a 400 carrying `code: "unknown_field"` and naming the offending field, rather than a 200 that silently dropped it.

Authenticated with the X-API-Key header.

Read the ICP (Ideal Customer Profile) criteria — filter rules and match mode — that decide which of this source's leads are `isIcp`, and with a webhook's `icpOnly`, which are delivered. ADDRESSED BY SOURCE ID, AND IT WORKS FOR EVERY KIND OF SOURCE — a person, a company page, a TRACKED POST or a KEYWORD SEARCH. The per-kind routes are keyed by whatever identifier that kind happens to have (/api/v1/{profile|company}/{username}/... by LinkedIn handle, /api/v1/keyword/{id}/... by source id), which is why a tracked post — whose identifier is an activity URN — had no route at all. It was never the SETTING that was missing: a tracked post is a tracked_profiles row like any other, its webhook fires through the same path, its leads are scored against the same ICP rules, and POST /api/v1/post/track has always returned a `syncId` from a real sync job. Only the addressing was. The scoring has always been kind-blind: capture evaluates these rules off the source row without regard for what kind of source it is. `rules: []` means no filter at all, which is not the same as a filter that matches nothing.

Authenticated with the X-API-Key header.