Skip to main content
POST

​
List Signal Leads

Returns the leads your engagement signals (keyword_engagement, industry_engagement, company_engagement, and person_engagement) have stored, newest first. Use it to read past leads: to backfill after a missed webhook, to rebuild a report, or to pull only what is new since your last call. The leads are always your own. They are found from your API key, so a request cannot name another account. This request costs no credits.

​
Request

Every attribute is optional. With none, you get your 50 most recent leads across all your signals. Filters combine: a lead has to match all of the ones you send.

​
Filters

​
string
Only leads found by this signal. Get the ID from /signal/create or /signal/list. A signal ID that is not yours returns an empty page.
​
integer
Only leads with a lead score of at least this, from 1 to 3.
​
integer
Only leads with a lead score of at most this, from 1 to 3. Must not be lower than min_score.
​
string
Only leads that this keyword, industry, company, or person label surfaced (the lead’s signal_keyword). Matches the whole value, in any letter case. Up to 200 characters.
​
string
How the person engaged: comment, like, or another reaction such as celebrate or support. Any letter case. Up to 50 characters.
​
string
Only leads whose name or headline contains this text, in any letter case. % and _ are matched as themselves. Up to 100 characters.
​
string
Only leads found at or after this moment, as an ISO 8601 date or time, for example 2026-09-01 or 2026-09-01T09:00:00Z. A date alone means the start of that day, and a time without a zone is read as UTC.
​
string
Only leads found before this moment, in the same format. Leads found exactly at this moment are not included. Must be later than created_from.

​
Sorting and paging

​
string
default:"created_at_desc"
The order of the leads:
  • created_at_desc: newest first (default)
  • created_at_asc: oldest first
  • lead_score_desc: highest lead score first, newest first among equal scores
  • icp_score_desc: best ICP fit first, newest first among equal scores
​
integer
default:"50"
Leads per page, from 1 to 200.
​
integer
default:"0"
Leads to skip, from 0 to 1000000. To go deeper than that, narrow the range with created_from and created_to.
Text values are trimmed of surrounding spaces. Any other attribute, including one that names a user or an email, is rejected with 400, so a misspelled filter cannot quietly return unfiltered leads.

​
Response

​
Response fields

​
object
​
integer
Always 0.

​
Getting all your leads

Your whole history. Page with limit and offset until has_more is false. Set created_to to the current time before your first request and keep it the same for the whole walk. Otherwise leads that arrive while you are paging shift the pages. Only what is new. Send sort as created_at_asc and created_from set a minute before the newest detected_at you already have, then skip any id you already hold. Leads from one run are stored together and share a detected_at, and the minute of overlap covers a run that finishes just after another.
detected_at is when a lead was first found. If a later run finds the same person for the same keyword, it updates that lead’s scores and post in place and keeps its detected_at, so a lead you already have can change without showing up again in a created_from request.

​
Notes

  • The lead fields are the same as in a webhook, plus id, signal_id, and icp_match_details. engagement_link is not included, because the link to the exact comment is not stored: use engagement_post_url.
  • Leads outlive their signal. Deleting a signal does not delete the leads it found, and they stay listed under its old signal_id.
  • Returns 400 for an invalid filter, with a message that names the attribute, for example min_score must be an integer from 1 to 3.
  • Returns 401 for an invalid API key, or when the account has no credits left, even though this request costs none.
  • Returns 403 if your account does not have access to Signals. Contact signals@datamagnet.co.
  • Returns 500 with Failed to fetch leads if the request could not be completed. Try again.