# Instagram 精选合集 API (instagram.highlights)

- Canonical page: https://everyinfra.com/instagram-api/highlights
- Endpoint: POST /api/v1/social with {"platform": "instagram", "action": "highlights", "params": {...}}
- Price: $0.001597 per call ($1.6 per 1,000 requests); failed and empty results are not charged
- Returns: list, default 100, max 100 per call (larger values are capped)
- Mode: sync; add "mode": "async" for slow tasks

Instagram 精选合集按 `username` 列出账号主页上的精选栏，每个合集一行：标题 `title`、封面 `cover_url`、合集里的快拍条数 `media_count`、创建时间 `created_at`，以及作者的用户名、显示名和 ID。读回来的是合集本身，适合看品牌或达人把哪些主题留在主页上、每个主题攒了多少条。

默认和上限都是 100 条，传更大的数也按 100 条返回，合集里每条快拍的内容不在这一页。`updated_at` 是最近一次往合集里加快拍的时间，可以用来判断这个合集还有没有人在维护；`is_pinned` 为真表示它被置顶在精选栏最前。

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| username | not declared | yes | not declared | 要看精选的 Instagram 账号用户名，如 nasa（可带 @，也收主页链接）。返回主页上的精选合集列表，不含合集里的每条快拍。 |
| limit | integer (1–100) | no | 100 | 这次调用最多返回的条数，整数，1–100；不传按默认值，实际返回可能少于这个数。超过上限照收，按上限返回。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| title | 标题。平台无标题概念时（如纯文本帖）为 null。 |
| media_count | 这个精选合集里的快拍条数（highlights）。 |
| cover_url | 精选封面图（highlights）。 |
| created_at | 创建时间，格式同 posted_at。 |
| updated_at | 精选最近一次加入快拍的时间（highlights；ISO 8601，UTC）。 |
| is_pinned | 是否被置顶在主页精选栏最前（highlights）。 |
| author_username | 作者用户名（@handle），通常可用于拼 URL。 |
| author_id | 作者在原平台的唯一 ID。 |
| author_name | 作者昵称（显示名）。 |
| 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": "instagram",
  "action": "highlights",
  "params": {
    "username": "nasa"
  }
}'
```

```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": "instagram",
        "action": "highlights",
        "params": {
            "username": "nasa",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

No real sample for these example parameters yet: structure only, every value is a placeholder (…).

```text
{
  "id": "req_…",
  "platform": "instagram",
  "action": "highlights",
  "results": [
    {
      "id": …,
      "url": …,
      "title": …,
      "media_count": …,
      "cover_url": …,
      "created_at": …,
      "updated_at": …,
      "is_pinned": …,
      "author_username": …,
      "author_id": …,
      "author_name": …,
      "platform": …
    }
  ],
  "count": …,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 精选合集里的每条快拍能在这一页拿到吗？

拿不到。这一页只返回合集的列表信息，每个合集有标题、封面和快拍条数 `media_count`，不含里面每条快拍。快拍那一页只返回发出 24 小时内、现在还在线的快拍，两页读的是不同的东西。

### `created_at` 和 `updated_at` 怎么区分？

`created_at` 是合集的创建时间，`updated_at` 是最近一次加入快拍的时间，格式都是 ISO 8601、UTC。两个时间差得远，说明合集建好后很久没有新增；想知道账号最近还在不在整理精选，看 `updated_at`，再对照 `is_pinned` 看哪个合集被放在最前。

### 这一页和快拍那一页怎么配合？

先用这一页看账号主页上有哪些精选主题、各有多少条，再用快拍那一页看账号此刻在线的快拍。两页都只要 `username`，也都默认返回 100 条、单次最多 100 条，请求写法不用另学。

## Also

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