---
title: "List people"
description: "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."
canonical: https://docs.rumoro.dev/api/people/list-people
markdown: https://docs.rumoro.dev/api/people/list-people.mdx
---

# List people

`GET /v1/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.

## Parameters

| Name | In | Description |
| --- | --- | --- |
| `platform` | query | Only people with a profile on this platform. |
| `q` | query | Searches the display name, handle and profile link, ignoring case. |
| `handle` | query | 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` | query | Keeps people with this tag, matched exactly and by case. |
| `muted` | query | true keeps muted people and false people who are not muted. Leave it out for everyone. |
| `since` | query | A time in ISO 8601 or epoch ms. Keeps people first matched then or later. |
| `segmentId` | query | Adds a saved segment's filter to all other filters here. An unknown id returns 404. |
| `platforms` | query | Keeps people who have an account on one of these platforms. Repeat the parameter or separate values with commas. |
| `tags` | query | Keeps people with one of these tags. Repeat the parameter or separate values with commas. |
| `minFollowers` | query | This many followers or more. People with an unknown count are left out. |
| `maxFollowers` | query | Keeps people with this many followers or fewer. |
| `minMentions` | query | Minimum number of matched mentions. |
| `minNegative` | query | Minimum number of negative mentions. |
| `intents` | query | Has a mention tagged with one of these intents. |
| `notPlatforms` | query | Leaves out people with an account on these platforms. Repeat the parameter or separate values with commas. |
| `notTags` | query | Leaves out people with one of these tags. Repeat the parameter or separate values with commas. |
| `notIntents` | query | Leaves out people whose mentions have one of these intents. Repeat the parameter or separate values with commas. |
| `keywordKinds` | query | Only people with a mention of these keyword kinds. |
| `neverKeywordKinds` | query | Excludes people who mentioned these keyword kinds. |
| `newSinceDays` | query | People first seen in the past this many days. |
| `linkHosts` | query | Keeps people with a mention that links to one of these hosts or its subdomains. Repeat the parameter or separate values with commas. |
| `stages` | query | Keeps people at one of these outreach stages. Repeat the parameter or separate values with commas. |
| `automated` | query | true keeps people whose matched posts are mostly machine-made, such as bots. false keeps the others. Leave it out for everyone. |
| `ownerIds` | query | 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` | query | 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` | query | How many to return, from 1 to 100. |
| `offset` | query | People to skip. Offset paging is for grouped lists of hundreds, not streams. |

## Responses

| Status | Meaning |
| --- | --- |
| 200 | A page of people |
| 400 | The query is not valid |
| 401 | The API key is missing or not valid |
| 404 | Your workspace has no segment with this id |

The [OpenAPI document](https://api.rumoro.dev/v1/openapi.json) has every schema. Rules shared by all endpoints are in [Conventions](https://docs.rumoro.dev/conventions.mdx).