Signals

A Signal is a rule that watches a LinkedIn entity or a search query and notifies you when something changes. You define the target, the schedule, and the match criteria. Up2Data runs the checks, stores every match, and delivers the diff to your webhook.

Signals, checks, Triggers

A Signal produces checks. A check whose criteria match produces a Trigger.

	What it is	Where you see it
Signal	The rule: target, schedule, criteria, notification	`/v1/signals`
Check	One scheduled scrape of the target. Runs at every interval, whether or not anything changed.	Billing line item and check log
Trigger	A check whose criteria matched. Stored and delivered to your webhook.	`/v1/triggers`

You create Signals and consume Triggers. Credits are spent on checks.

What it costs

Signals draw from the same prepaid credit balance as the rest of the API. There is no subscription and no billing cycle. Each check deducts the cost of its underlying scrape when it runs:

Target	Credits per check
`profile`, `company`, `post`	1
`profile_list` (N URLs)	1 × N
Search-backed (`company_jobs`, `post_search`, `people_search`, `company_search`)	1 per page of 25 results
Post engagers (`post_reactions`, `post_comments`, `post_reposts`)	1 × returned engagers

Spend scales with the schedule. A profile Signal on a 7d interval costs 1 credit a week. A 500-profile list checked daily costs 500 credits a day. A daily net-new people search at max_results: 50 costs 2 credits a day (2 pages × 1 credit). Every check that completes is billable, whether or not it triggers. There is no separate fee for Triggers.

Outcome	Charged?
Baseline check (first check — establishes the snapshot, can never trigger)	Yes — `reason: "baseline_established"`
Check runs, no match	Yes
Check runs, Trigger fires	Yes — no extra fee
Scrape fails (deleted, timeout)	No

For profile_list, this applies per member: a partial check bills only the profiles that scraped successfully and carries failed members’ previous snapshots forward. If every profile fails, the check is free. To watch and cap spend:

estimated_monthly_credits, returned when you create a Signal, is its projected spend at the current schedule.
credits_used_this_month on every Signal attributes spend to each rule.
monitoring.monthly_check_budget on your account caps total check spend. When the cap is reached, Signals pause.

Platform attribution

Pass external_id and optional metadata when you create Signals on behalf of a tenant or end user. We echo those fields on Triggers, webhook payloads, and GET /v1/usage/signals rollups so you can attribute spend without maintaining a parallel ID map. Trigger history and check logs are retained for 90 days (all plans today).

Signals pause; they never silently skip. Insufficient balance, an exhausted check budget (paused_reason: "budget_exceeded"), or a dead webhook URL all flip the Signal to paused and fire a signal.paused event. Top up or fix, then resume.

2 types of Signals

Both use the same object. They answer different questions:

	Entity Signals	Net-new Signals
Target	Known URL(s): profile, company, post, job board	A query: people / company / post search (filters or Sales Nav URL)
Question	Did this thing change?	Did anyone new enter this set?
Snapshot	One record (or a fixed list)	Identity set of search results (URN → URL)
Typical criteria	`field_change`, `numeric_change`, `text_match`, `expression`	`new_entity`
Trigger payload	`diff.headline: { before, after }`	`diff.added: [stubs…]`
Sales Nav analog	Alerts on a saved lead / account	Alerts on a saved search

When to use which

You want…	Use
Know when Jane Doe changes title	`profile` + `field_change`
Know when Acme’s headcount moves	`company` + `numeric_change`
Know when Acme posts a new senior eng role	`company_jobs` + `new_entity`
Know when a new CTO appears in your ICP	`people_search` + `new_entity` ← net-new
Know when someone posts a buying-intent phrase	`post_search` + `text_match` (or `new_entity` if you only care about brand-new posts)
Know when a new person reacts / comments / shares a post	`post_reactions` / `post_comments` / `post_reposts` + `new_entity`

Net-new is a search-backed target with criteria.mode: new_entity, not a separate product. See recipe 6 in the Signals cookbook.

The Signal object

POST /v1/signals
{
  "name": "CTO job change alert",
  "tags": ["q3-pipeline", "champions"],
  "enabled": true,
  "schedule": {
    "interval": "1d",
    "timezone": "America/New_York",
    "anchor": "2026-07-07T09:00:00Z"
  },
  "target": {
    "type": "profile",
    "linkedin_url": "https://linkedin.com/in/example"
  },
  "criteria": {
    "mode": "field_change",
    "fields": ["headline", "position", "company"]
  },
  "notify": {
    "webhook_url": "https://app.example.com/hooks/up2data",
    "webhook_secret": "whsec_..."
  }
}

Target types

`target.type`	Watches	Credits per check
`profile`	One profile URL	1
`profile_list`	Up to 1,000 URLs in one Signal	1 × targets
`company`	One company URL	1
`company_jobs`	A company’s job board + filters	Search rate (1 / page of 25)
`post`	One post URL	1
`post_search`	Keyword/hashtag post query	Search rate (1 / page of 25)
`people_search`	People filters or Sales Nav URL	Search rate (1 / page of 25)
`company_search`	Company filters or Sales Nav URL	Search rate (1 / page of 25)
`post_reactions`	Reactors on a post URL	1 × returned engagers
`post_comments`	Commenters on a post URL	1 × returned engagers
`post_reposts`	Reposters/sharers on a post URL	1 × returned engagers

Entity targets bill one scrape per successful target per check. Search-backed targets re-run the query each check. Post-engager targets scrape the inbound engagement list and diff people (by profile URN/URL) with new_entity. Set max_results (default 25, max 100); search billing matches the underlying search, engager billing matches /v1/posts/engagement/*. Pass either structured filters or a sales_nav_url on people and company search targets. For post_reactions, optional filters.reaction_type mirrors the reactions endpoint.

Schedule

"schedule": {
  "interval": "15m" | "1h" | "6h" | "1d" | "7d" | "30d",
  "timezone": "America/New_York",
  "anchor": "2026-07-07T09:00:00Z"
}

Minimum interval is 15m. The interval determines how often checks run, and therefore what the Signal costs (see What it costs). The optional anchor aligns the cadence, for example a 1d Signal that always checks at 9am local time. Checks get slight jitter to keep delivery smooth; next_check_at on every Signal tells you exactly when the next one runs.

Criteria modes

`criteria.mode`	Fires when
`field_change`	A watched field differs from the last snapshot
`text_match`	Text content matches `contains` / `any_of[]` / `regex`
`new_entity`	A new job / post / person / company appears vs the prior result set (net-new)
`field_equals`	A field equals a value (fire once, or on every change into it)
`numeric_change`	A numeric field moves by ≥ `min_change_pct` / `min_change_abs`
`expression`	A CEL expression over `snapshot` + `diff` evaluates true

field_change with thresholds

"criteria": {
  "mode": "field_change",
  "fields": [
    "headline",
    { "name": "headcount", "min_change_pct": 2 }
  ]
}

text_match on posts

"criteria": {
  "mode": "text_match",
  "field": "text",
  "any_of": ["hiring", "we're growing"]
}

Matching is always case-insensitive (values are normalized before compare). By default a Trigger re-fires only when the value changes again (refire: on_change_only). Set refire: always for repeat alerts on every matching check.

Net-new (Sales Nav saved search)

Sales Navigator lets you save a search and get notified when new people or companies enter the result set. Up2Data does the same with people_search or company_search plus new_entity:

{
  "name": "Net-new CTOs in US SaaS",
  "schedule": { "interval": "1d" },
  "target": {
    "type": "people_search",
    "filters": {
      "titles": ["CTO", "Chief Technology Officer"],
      "location_ids": [
        { "id": "103644278", "text": "United States" }
      ],
      "company_sizes": ["51-200", "201-500"]
    },
    "max_results": 50
  },
  "criteria": { "mode": "new_entity" }
}

Singular aliases such as title, location_id, industry_id, and company_size are accepted and normalized to their plural forms. LinkedIn location, industry, company, and school facets require IDs; a name such as "location": "United States" is rejected with a precise validation error rather than silently broadening the search. Or paste the Sales Nav URL you already use:

"target": {
  "type": "people_search",
  "sales_nav_url": "https://www.linkedin.com/sales/search/people?...",
  "max_results": 50
}

The first check is the baseline. It stores the identity set (URN, else URL) and never triggers. Every later check re-runs the search, diffs identities, and fires only on additions by default (include_removals: false). The Trigger’s diff.added[] carries the new stubs; pipe URLs into batch enrich if you want full profiles.

Filtering

A change only fires a Trigger if it means something. Three rules govern entity diffs:

Strings compare normalized. Case, whitespace and punctuation drift from re-scrapes don’t fire; real token changes (“VP Eng @ Acme” → “CTO @ Beta”) do.
Volatile fields are excluded from fields: ["*"] — followers_count, connections_count, post engagement counts, photo/media URLs. Watch them by naming them explicitly, ideally with a threshold.
Numeric fields take thresholds. { "name": "headcount", "min_change_pct": 2 } means 2,841 → 2,843 stays silent; 2,841 → 2,950 fires. Without a threshold, any delta fires.

For net-new (new_entity), identity is by URN (else URL). Only additions fire by default. People dropping out of a search window stay silent unless you set include_removals: true. Diffable fields are the same fields the enrichment API returns; each endpoint’s field glossary is the reference.

Signals at scale

Most production setups watch hundreds or thousands of entities:

Tags on every Signal: filter GET /v1/signals?tag= and GET /v1/triggers?tag=
Bulk create: one template × up to 1,000 targets → N Signals in one call
Bulk pause/resume by tag: POST /v1/signals/pause with { "tag": "q3-pipeline" } — see Pause
Account-level notify defaults (PATCH /v1/account): set default_webhook_url once instead of on every Signal

Triggers

Every Trigger’s diff and snapshot are stored durably for 90 days (all plans today) and delivered to the Signal’s webhook. Entity change (field moved):

{
  "event": "signal.triggered",
  "trigger_id": "trg_abc123",
  "check_number": 41,
  "signal": { "id": "sig_xyz", "name": "CTO job change alert", "tags": ["q3-pipeline"] },
  "target": { "type": "profile", "linkedin_url": "https://linkedin.com/in/example" },
  "diff": {
    "headline": { "before": "VP Eng @ Acme", "after": "CTO @ Beta" }
  },
  "snapshot": { "full_name": "…", "headline": "CTO @ Beta" },
  "checked_at": "2026-07-07T14:00:00Z"
}

Net-new (someone entered the search set):

{
  "event": "signal.triggered",
  "trigger_id": "trg_def456",
  "check_number": 12,
  "signal": { "id": "sig_abc", "name": "Net-new CTOs in US SaaS", "tags": ["inbound-tam"] },
  "target": { "type": "people_search", "max_results": 50 },
  "diff": {
    "added": [
      {
        "url": "https://linkedin.com/in/new-cto",
        "full_name": "Alex Rivera",
        "headline": "CTO at Example",
        "urn": "ACoAA…"
      }
    ]
  },
  "checked_at": "2026-07-10T09:00:00Z"
}

Destination — set a webhook on the Signal, or omit notify to use the account default:

"notify": {
  "webhook_url": "https://app.example.com/hooks/up2data",
  "webhook_secret": "whsec_..."
}

Deliveries are not globally ordered. Each Trigger carries a per-Signal monotonic check_number; order by it and dedupe by trigger_id. Signing, retries and auto-pause rules live in Webhooks. Missed a delivery? Everything is queryable via GET /v1/triggers.

When to use this

Use Signals when you care about changes over time: job moves, headcount jumps, new people entering a search, posts that match a phrase. Use the enrichment API when you need data once. Credits are the same either way; Signals replaces the scheduling, snapshot storage, diffing, and delivery you would otherwise build and run yourself.

	Enrichment (one-shot)	Signals
Job	Get data now	Watch for change, get notified
Change detection	You store snapshots and diff	We store snapshots and diff
Noise control	You normalize and threshold	Normalized diffs + thresholds built in
Delivery	You schedule and poll	Webhook pushed to you
Cost	Same scrape cost + your infra	Same scrape cost, zero infra
History	Yours to build	`GET /v1/triggers`, built in

Signals cookbook

Copy-paste recipes: job-change alerts, net-new ICP searches, fleet monitoring, cost estimation.

Getting started

CLI & MCP

Concepts

Signals, checks, Triggers

What it costs

Platform attribution

2 types of Signals

When to use which

The Signal object

Target types

Schedule

Criteria modes

Net-new (Sales Nav saved search)

Filtering

Signals at scale

Triggers

When to use this

Signals cookbook

​Signals, checks, Triggers

​What it costs

​Platform attribution

​2 types of Signals

​When to use which

​The Signal object

​Target types

​Schedule

​Criteria modes

​Net-new (Sales Nav saved search)

​Filtering

​Signals at scale

​Triggers

​When to use this

Signals cookbook

Signals, checks, Triggers

What it costs

Platform attribution

2 types of Signals

When to use which

The Signal object

Target types

Schedule

Criteria modes

Net-new (Sales Nav saved search)

Filtering

Signals at scale

Triggers

When to use this