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

# List people

`GET /v1/people`

## Request

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

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.

## Query parameters

- `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps': Only people with a profile on this platform.
- `q` string: Searches the display name, handle and profile link, ignoring case.
- `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.
- `tag` string: Keeps people with this tag, matched exactly and by case.
- `muted` boolean: true keeps muted people and false people who are not muted. Leave it out for everyone.
- `since` string, date-time: A time in ISO 8601 or epoch ms. Keeps people first matched then or later.
- `segmentId` string: Adds a saved segment's filter to all other filters here. An unknown id returns 404.
- `platforms` string[]: Keeps people who have an account on one of these platforms. Repeat the parameter or separate values with commas.
- `tags` string[], nullable: Keeps people with one of these tags. Repeat the parameter or separate values with commas.
- `minFollowers` integer, nullable: This many followers or more. People with an unknown count are left out.
- `maxFollowers` integer, nullable: Keeps people with this many followers or fewer.
- `minMentions` integer: Minimum number of matched mentions.
- `minNegative` integer: Minimum number of negative mentions.
- `intents` string[], nullable: Has a mention tagged with one of these intents.
- `notPlatforms` string[]: Leaves out people with an account on these platforms. Repeat the parameter or separate values with commas.
- `notTags` string[], nullable: Leaves out people with one of these tags. Repeat the parameter or separate values with commas.
- `notIntents` string[], nullable: Leaves out people whose mentions have one of these intents. Repeat the parameter or separate values with commas.
- `keywordKinds` string[]: Only people with a mention of these keyword kinds.
- `neverKeywordKinds` string[]: Excludes people who mentioned these keyword kinds.
- `newSinceDays` integer: People first seen in the past this many days.
- `linkHosts` string[], nullable: Keeps people with a mention that links to one of these hosts or its subdomains. Repeat the parameter or separate values with commas.
- `stages` string[]: Keeps people at one of these outreach stages. Repeat the parameter or separate values with commas.
- `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` string[], nullable: 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.
- `sort` 'mentions' | 'recent' | 'reach' | 'new': 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.
- `limit` integer: How many to return, from 1 to 100.
- `offset` integer, nullable: People to skip. Offset paging is for grouped lists of hundreds, not streams.

## Response `200`

A page of people

- object
  - `data` object[], required
    - `id` string, required: The person's id (aut_...), which is the id of their main account. An account merged into a person leads to that person.
    - `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss', required: The main account's platform. See `accounts` for all of them.
    - `name` string, nullable, required: The name shown on their latest post. Null if the platform has none.
    - `handle` string, nullable, required: The main account's handle, written the platform's way.
    - `url` string, nullable, required: Link to the main account's profile.
    - `avatarUrl` string, nullable, required
    - `accounts` object[], required: All accounts this workspace counts as this person, starting with the main one.
      - `id` string, required: The account's id (aut_...). The main account's id is the person's id.
      - `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss', required: The platform. Review platforms are appstore, googleplay, trustpilot and googlemaps (a place's Google reviews).
      - `name` string, nullable, required: The name shown on the platform.
      - `handle` string, nullable, required: The handle taken from the profile link, written the platform's way.
      - `url` string, nullable, required: Link to the profile.
    - `reach` object, required: Counts from the platform, taken from their latest post. Null where a platform lacks the number.
      - `followers` integer, nullable, required
      - `following` integer, nullable, required
      - `posts` integer, nullable, required
    - `profile` object, nullable, required: Details from the public profile. Null until the profile is fetched.
      - `bio` string, nullable, required
      - `company` string, nullable, required
      - `location` string, nullable, required
      - `website` string, nullable, required
      - `email` string, nullable, required: Filled in only for a public address on the platform.
      - `links` object[], required: Other accounts linked from the person's profile.
        - `provider` string, required
        - `url` string, uri, required
      - `fetchedAt` string, required: Last profile fetch time.
    - `stats` object, required: Counted from this workspace's matches only.
      - `mentions` integer, required: All their matches in this workspace, relevant or not.
      - `relevant` integer, required: How many of them scored as relevant.
      - `sentiment` object, required
        - `positive` integer, required
        - `neutral` integer, required
        - `negative` integer, required
      - `firstSeenAt` string, required: Time of their first matched post.
      - `lastSeenAt` string, required: Time of their latest matched post.
    - `annotations` object, required: Notes and tags your workspace added to the person.
      - `tags` string[], required
      - `notes` string, required
      - `muted` boolean, required: Their posts are kept out of the feed and all channels. Collection and billing still happen.
    - `outreach` object, required: Your outreach to this person. Logging the first activity makes the member who reached out the owner, if there was none, and moves not_contacted to contacted.
      - `owner` object, nullable, required: The teammate responsible for this contact. Null when no one is, or when that member has left the workspace.
        - `id` string, required: The member's user id.
        - `name` string, nullable, required
        - `email` string, nullable, required
      - `stage` 'not_contacted' | 'contacted' | 'replied' | 'in_talks' | 'customer' | 'not_a_fit', required: The outreach stage your team has reached with this person.
      - `lastContactedAt` string, nullable, required: Time of the latest logged activity. Null when no contact was logged.
  - `total` integer, required: How many people match the filters, over all pages.

## Other responses

- `400`: The query is not valid
- `401`: The API key is missing or not valid
- `404`: Your workspace has no segment with this id

---

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