OverviewPlatformsAPI Reference
People

List people

Returns the authors of your mentions, one row per person. Each row has their accounts, reach, public profile, stats for this workspace, your notes and tags, and your outreach status. You can filter by platform, tag, follower range, mention counts, intents, keyword kinds they did or did not mention, outreach stage, owner, automated (bots whose matched posts are mostly machine-made) or a saved segment. Pages use offset and include a total.

GET
/v1/people

Authorization

bearerAuth
AuthorizationBearer <token>

An API key from POST /v1/api-keys. Keys start with ref_.

In: header

Query Parameters

platform?string

Only people with a profile on this platform.

Value in

  • "bluesky"
  • "hackernews"
  • "github"
  • "stackoverflow"
  • "devto"
  • "reddit"
  • "x"
  • "youtube"
  • "news"
  • "linkedin"
  • "tiktok"
  • "instagram"
  • "appstore"
  • "googleplay"
  • "trustpilot"
  • "googlemaps"
q?string

Searches the display name, handle and profile link, ignoring case.

Length1 <= length <= 200
handle?string

Looks up a person by one of their accounts, given as a handle (@sam, u/sam, sam) or a profile or post link (https://x.com/sam). The match is exact but ignores case, and covers merged accounts. Add platform to pick one platform. A link already tells which platform it is.

Length1 <= length <= 300
tag?string

Keeps people with this tag, matched exactly and by case.

Length1 <= length <= 40
muted?boolean

true keeps muted people and false people who are not muted. Leave it out for everyone.

since?string

A time in ISO 8601 or epoch ms. Keeps people first matched then or later.

Formatdate-time
segmentId?string

Adds a saved segment's filter to all other filters here. An unknown id returns 404.

Length1 <= length
platforms?array<>

Keeps people who have an account on one of these platforms. Repeat the parameter or separate values with commas.

Itemsitems <= 20
tags?array<>|

Keeps people with one of these tags. Repeat the parameter or separate values with commas.

Itemsitems <= 20
minFollowers?|

This many followers or more. People with an unknown count are left out.

Range0 <= value
maxFollowers?|

Keeps people with this many followers or fewer.

Range0 <= value
minMentions?integer

Minimum number of matched mentions.

Range1 <= value
minNegative?integer

Minimum number of negative mentions.

Range1 <= value
intents?array<>|

Has a mention tagged with one of these intents.

Itemsitems <= 10
notPlatforms?array<>

Leaves out people with an account on these platforms. Repeat the parameter or separate values with commas.

Itemsitems <= 20
notTags?array<>|

Leaves out people with one of these tags. Repeat the parameter or separate values with commas.

Itemsitems <= 20
notIntents?array<>|

Leaves out people whose mentions have one of these intents. Repeat the parameter or separate values with commas.

Itemsitems <= 10
keywordKinds?array<>

Only people with a mention of these keyword kinds.

Itemsitems <= 3
neverKeywordKinds?array<>

Excludes people who mentioned these keyword kinds.

Itemsitems <= 3
newSinceDays?integer

People first seen in the past this many days.

Range1 <= value <= 365
linkHosts?array<>|

Keeps people with a mention that links to one of these hosts or its subdomains. Repeat the parameter or separate values with commas.

Itemsitems <= 20
stages?array<>

Keeps people at one of these outreach stages. Repeat the parameter or separate values with commas.

Itemsitems <= 6
automated?boolean

true keeps people whose matched posts are mostly machine-made, such as bots. false keeps the others. Leave it out for everyone.

ownerIds?array<>|

Keeps people owned by one of these members, by user id. Use none for people without an owner. Repeat the parameter or separate values with commas.

Itemsitems <= 20
sort?string

mentions puts the most matches first. recent puts the most recently seen first. reach puts the most followers first, with unknown counts at the end. new puts people seen for the first time most recently first.

Default"mentions"

Value in

  • "mentions"
  • "recent"
  • "reach"
  • "new"
limit?integer

How many to return, from 1 to 100.

Range1 <= value <= 100
Default50
offset?|

People to skip. Offset paging is for grouped lists of hundreds, not streams.

Range0 <= value
Default0

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/people"
{  "data": [    {      "id": "string",      "platform": "bluesky",      "name": "string",      "handle": "string",      "url": "string",      "avatarUrl": "string",      "accounts": [        {          "id": "string",          "platform": "bluesky",          "name": "string",          "handle": "string",          "url": "string"        }      ],      "reach": {        "followers": 0,        "following": 0,        "posts": 0      },      "profile": {        "bio": "string",        "company": "string",        "location": "string",        "website": "string",        "email": "string",        "links": [          {            "provider": "string",            "url": "http://example.com"          }        ],        "fetchedAt": "string"      },      "stats": {        "mentions": 0,        "relevant": 0,        "sentiment": {          "positive": 0,          "neutral": 0,          "negative": 0        },        "firstSeenAt": "string",        "lastSeenAt": "string"      },      "annotations": {        "tags": [          "string"        ],        "notes": "string",        "muted": true      },      "outreach": {        "owner": {          "id": "string",          "name": "string",          "email": "string"        },        "stage": "not_contacted",        "lastContactedAt": "string"      }    }  ],  "total": 0}
Was this page helpful?

Get a person

Fetches a person, with your workspace's own data on them. The id of a merged account returns the person it was merged into.

List outreach activities

Returns up to 200 logged contacts with this person over all their accounts, latest first. Each shows who reached out, the channel, the time and a short note. Check it before you reach out, so two teammates don't contact the same person unaware.