# Bluesky 粉丝列表 API (bluesky.followers)

- Canonical page: [https://everyinfra.com/bluesky-api/followers](https://everyinfra.com/bluesky-api/followers?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "bluesky", "action": "followers", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 30, max 100 per call
- Mode: sync; add "mode": "async" for slow tasks

Bluesky 粉丝列表按完整 handle `username` 列出关注这个账号的人，每行带 `user_id`、显示名、个人简介 `bio`、头像、主页链接、认证标识和注册时间 `joined_at`。它回答「谁在关注这个账号」，适合分析一个创作者或机构在 Bluesky 上的受众构成，或者按简介里的关键词筛出粉丝中的研究者、记者和开发者。

`username` 只认完整 handle 或自定义域名，昵称和 bsky.app 的主页链接都不行。几份粉丝名单合并以后，靠 `source_username` 认出每一行属于哪个账号。一次最多拿 100 个粉丝，粉丝多的账号拿到的只是其中一部分，算受众比例时要把这一点记在结论旁边。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=bluesky&action=followers

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| username | not declared | yes | not declared | Bluesky 完整 handle，例如 alice.bsky.social 或账号绑定的自定义域名；不是显示昵称，也不要传 bsky.app/profile/ 页面 URL。profile、user_posts、followers、following 均用同一账号 handle 定位。 |
| limit | integer (1–100) | no | 30 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| user_id | 用户在原平台的唯一 ID。 |
| username | 用户名（@handle）。 |
| display_name | 显示名，可能与 username 不同。 |
| bio | 个人简介，账号自己填写的文本。可能含换行和 emoji。 |
| url | 该记录在原平台上的可访问链接。 |
| avatar_url | 头像图片链接。部分平台给的是带尺寸参数的 CDN 链接，可能有时效。 |
| is_verified | 是否为平台认证账号（蓝V等）。null 表示无法判定。 |
| joined_at | 账号注册时间。 |
| source_username | 这一行所在名单的所属账号，只在 followers、following 里出现，就是请求里的 username。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "bluesky",
  "action": "followers",
  "params": {
    "username": "bsky.app"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "bluesky",
        "action": "followers",
        "params": {
            "username": "bsky.app",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-09-26T08:56:04Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 30. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "bluesky",
  "action": "followers",
  "results": [
    {
      "user_id": "•••",
      "username": "•••",
      "display_name": "•••",
      "url": "https://bsky.app/•••",
      "avatar_url": "https://cdn.bsky.app/•••",
      "is_verified": false,
      "joined_at": "2025-12-22T12:18:03.125000+00:00",
      "source_username": "bsky.app",
      "platform": "bluesky"
    },
    {
      "user_id": "•••",
      "username": "•••",
      "display_name": "•••",
      "url": "https://bsky.app/•••",
      "avatar_url": "https://cdn.bsky.app/•••",
      "is_verified": false,
      "joined_at": "2026-05-23T11:52:04.564000+00:00",
      "source_username": "bsky.app",
      "platform": "bluesky"
    }
  ],
  "count": 30,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### `joined_at` 能看出什么？

`joined_at` 是粉丝账号的注册时间。把一份粉丝名单按注册月份分组，就能看出这个账号的受众是早期用户居多，还是最近才加入的新用户；注册日期集中在某一段时间的那批账号，可以单独拉出来对照。它不是关注你的时间，没法据此判断某位粉丝是哪天关注的。扎堆注册的那批账号，再对照它们的显示名和简介找共同点。统计前把 `limit` 设到 100，默认的 30 条样本太小；时间截到年月再计数，画成柱状图，哪几个月注册的粉丝最多一眼就能看出。

### 为什么传昵称或主页链接查不到？

这项能力只认完整 handle。显示昵称可以重名，bsky.app/profile/ 开头的页面链接也不收；从链接里取出 profile/ 后面那段，例如 alice.bsky.social，填进 `username` 即可。页面示例填的 bsky.app 本身也是一个完整 handle，不是网址。粉丝行里的 `username` 同样是完整 handle，想继续看某位粉丝的主页资料或帖子，原样拿去调就行，不用再做转换；绑了自定义域名的账号，填域名本身。

### 粉丝列表和关注列表怎么选？

要看谁关注了这个账号，用粉丝列表；要看这个账号自己关注了谁，用关注列表。两者参数和返回列相同，`source_username` 都是请求里的账号，合并存储时另加一列标明是哪个方向的名单。想知道受众里认证账号占多少，数 `is_verified` 为真的行；为 null 是无法判定，别算成未认证。竞品几个账号的粉丝名单里重复出现的 `user_id`，就是这几个账号共同的受众，投放或合作时可以优先触达这批人。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=bluesky
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
