---
title: "List people"
method: GET
path: "/v1/people"
tags: ["People"]
---

# List people

`GET /v1/people`

## Request

- Base URL: `https://api.mentio.dev`
- URL: `https://api.mentio.dev/v1/people`
- Auth: HTTP bearer

The people behind your mentions: one row per person, with their accounts, reach, public profile, per-workspace stats, your annotations and where your outreach stands. Filter by platform, tag, follower range, mention counts, intents seen, keyword kinds mentioned or never mentioned, outreach stage, owner, automated (bot accounts, whose matched posts are mostly machine-made), or a saved segment. Offset-paginated with a total. With `groupId`, only the people who mentioned that keyword group's keywords, counted over those mentions, with that group's own annotations, merges, outreach and segments.

## Query parameters

- `groupId` string: Scope to one keyword group (grp_...): only people who mentioned that group's keywords, with that group's own tags, notes, mute, merges, activities and segments. Omit for the whole workspace.
- `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss': People with an account on this platform.
- `q` string: Matches the display name or the profile handle or URL, case-insensitively.
- `handle` string: Find a person by one of their accounts: a handle (@jane, u/jane, jane) or a profile or post link (https://x.com/jane). Exact, case-insensitive, merged accounts included; combine with platform to pick one platform. A link names its own platform.
- `tag` string: Only people carrying this tag (exact, case-sensitive).
- `muted` boolean: true: only muted people; false: only unmuted; omitted: everyone.
- `since` string, date-time: Only people whose first matched mention is at or after this instant (ISO 8601, or epoch ms).
- `segmentId` string: A saved segment applied on top of every other filter here. Unknown id: 404.
- `platforms` string[]: People with an account on any of these platforms. Repeatable, or comma-separated.
- `tags` string[], nullable: People carrying any of these tags. Repeatable, or comma-separated.
- `minFollowers` integer, nullable: At least this many followers. Unknown reach never matches.
- `maxFollowers` integer, nullable: At most this many followers.
- `minMentions` integer: At least this many matched mentions.
- `minNegative` integer: At least this many negative mentions.
- `intents` string[], nullable: At least one mention carrying any of these intents.
- `notPlatforms` string[]: Nobody with an account on these platforms. Repeatable, or comma-separated.
- `notTags` string[], nullable: Nobody carrying any of these tags. Repeatable, or comma-separated.
- `notIntents` string[], nullable: Nobody whose mentions carry any of these intents. Repeatable, or comma-separated.
- `keywordKinds` string[]: Mentioned a keyword of any of these kinds.
- `neverKeywordKinds` string[]: Never mentioned a keyword of these kinds.
- `newSinceDays` integer: First seen within this many days.
- `linkHosts` string[], nullable: People with at least one mention linking to any of these hosts, the host itself or a subdomain of it. Repeatable, or comma-separated.
- `stages` string[]: People at any of these outreach stages. Repeatable, or comma-separated.
- `automated` boolean: true: only people whose matched posts are mostly machine-made (bot accounts); false: only the rest; omitted: everyone.
- `ownerIds` string[], nullable: People owned by any of these members (user ids); `none` matches people nobody owns. Repeatable, or comma-separated.
- `sort` 'mentions' | 'recent' | 'reach' | 'new': mentions: most matches first. recent: last seen first. reach: most followers first, unknown last. new: first seen most recently first.
- `limit` integer: Page size, 1 to 100.
- `offset` integer, nullable: Skip this many people. Offset paging: a grouped read over hundreds of people, not a stream.

## Response `200`

One page of people

- object
  - `data` object[], required
    - `id` string, required: Person id (aut_...): the canonical account. An account merged into someone resolves to that person.
    - `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss', required: Platform of the canonical account; `accounts` lists every account.
    - `name` string, nullable, required: Display name as of their newest post; null when the platform has none.
    - `handle` string, nullable, required: Platform handle of the canonical account, formatted as the platform shows it.
    - `url` string, nullable, required: Profile URL of the canonical account.
    - `avatarUrl` string, nullable, required
    - `accounts` object[], required: Every account this workspace treats as this person, the canonical one first.
      - `id` string, required: The account id (aut_...); the canonical one equals the person id.
      - `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss', required: Platform: bluesky, hackernews, github, stackoverflow, devto, reddit, x, youtube, news, linkedin, tiktok, instagram, appstore (App Store reviews), googleplay (Google Play reviews), trustpilot (Trustpilot reviews), googlemaps (Google reviews of a place), rss (RSS and Atom feeds a keyword reads).
      - `name` string, nullable, required: Display name as the platform reports it.
      - `handle` string, nullable, required: Platform handle derived from the profile URL, formatted as the platform shows it.
      - `url` string, nullable, required: Profile URL.
    - `reach` object, required: Platform counts as of their newest post; null where the platform has no such number.
      - `followers` integer, nullable, required
      - `following` integer, nullable, required
      - `posts` integer, nullable, required
    - `profile` object, nullable, required: Public profile facts; null until looked up.
      - `bio` string, nullable, required
      - `company` string, nullable, required
      - `location` string, nullable, required
      - `website` string, nullable, required
      - `email` string, nullable, required: Only when the person made it public on the platform.
      - `links` object[], required: Other accounts the person lists on their profile.
        - `provider` string, required
        - `url` string, uri, required
      - `fetchedAt` string, required: When the profile was read.
    - `stats` object, required: Computed over this workspace's matches.
      - `mentions` integer, required: Every match of theirs for this workspace, relevant or not.
      - `relevant` integer, required: Of those, scored relevant.
      - `sentiment` object, required
        - `positive` integer, required
        - `neutral` integer, required
        - `negative` integer, required
      - `firstSeenAt` string, required: Their oldest matched post.
      - `lastSeenAt` string, required: Their newest matched post.
    - `annotations` object, required: What this workspace wrote about the person.
      - `tags` string[], required
      - `notes` string, required
      - `muted` boolean, required: Their posts stay out of the feed and every channel; ingest and billing are untouched. Read with groupId it is that group's own mute, which hides them from the mentions of that group's keywords only.
    - `outreach` object, required: Where your workspace stands with the person. The first logged activity claims an unowned person for whoever reached out and moves not_contacted to contacted.
      - `owner` object, nullable, required: The teammate who owns the contact; null when nobody does, or the owner left the workspace.
        - `id` string, required: User id of the workspace member.
        - `name` string, nullable, required
        - `email` string, nullable, required
      - `stage` 'not_contacted' | 'contacted' | 'replied' | 'in_talks' | 'customer' | 'not_a_fit', required: Where your workspace stands with the person: not_contacted, contacted, replied, in_talks, customer or not_a_fit.
      - `lastContactedAt` string, nullable, required: The newest logged activity; null when nobody logged a contact.
  - `total` integer, required: People matching the filters, across all pages.

## Other responses

- `400`: Invalid query
- `401`: Missing or invalid API key
- `404`: No such segment in this scope, or no such group

---

[API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)