# How do I get Instagram Reel play counts?

Instagram. Checked September 2026.

Call the Openhandle post endpoint with the Reel ID, or list a profile’s reels with the reels endpoint. The play count is `metrics.views`. It is the number Instagram shows under the reel, as an integer, for any public account.

For an image or a carousel `metrics.views` is `null`. Those posts have no plays, and we do not write a zero for a number that does not exist.

## GET /v1/instagram/profiles/@username/reels

```bash
curl "https://api.openhandle.dev/v1/instagram/profiles/@northstar_forge_test/reels" \
  -H "Authorization: Bearer $OPENHANDLE_API_KEY"
```

```ts
import { OpenHandle } from '@openhandle/sdk';

const openhandle = new OpenHandle({ apiKey: process.env.OPENHANDLE_API_KEY! });
const page = await openhandle.instagram.profile('northstar_forge_test').reels.list();

for (const reel of page.data) console.log(reel.id, reel.metrics.views);
```

200 OK:

```json
{
  "platform": "instagram",
  "resource": "post",
  "capturedAt": "2026-09-18T11:33:12Z",
  "source": "live",
  "data": [
    {
      "id": "910100000001",
      "type": "video",
      "createdAt": "2026-08-09T15:30:00Z",
      "metrics": { "views": 12000, "likes": 840, "comments": 5, "shares": 21 }
    }
  ],
  "meta": { "cursors": { "next": "b3BhcXVlLWN1cnNvcg" } }
}
```

Trimmed to one reel and its metrics. The example is a Test profile with a paginated reel feed, so you can run it on a free Test key.

## Where the number comes from

Instagram shows a play count on public reels. Openhandle reads that number when you ask. It is not reach, not unique viewers, and not the owner’s insights. Those live in the owner’s analytics and are not public. See [metric semantics](/docs/concepts/metric-semantics) for what each metric means per platform.

## Three ways to get there

- **From a profile.** `GET /v1/instagram/profiles/@username/reels` lists reels newest first, one page per request.
- **From a reel URL.** Pass the URL to `POST /v1/urls/fetch`. It returns the reel with its ID and metrics in one call.
- **From a hashtag.** `GET /v1/instagram/hashtags/{name}/reels` lists reels under a hashtag.

## Campaign reports

Read with `?freshness=live` when the number goes in a report or decides a payout. Store `capturedAt` next to it. Read again a week later to see growth. Hidden like counts on the same reel come back as `null` and should stay out of your averages.

## When this does not work

These answers are definitive. Store them, do not retry them.

| Situation | Status | Code |
|---|---|---|
| The reel is deleted or never existed | 404 | `POST_NOT_FOUND` |
| The account is private | 403 | `PROFILE_PRIVATE` |
| The identifier is malformed | 400 | `INVALID_IDENTIFIER` |

```json
{
  "error": {
    "code": "POST_NOT_FOUND",
    "message": "This post was not found.",
    "requestId": "req_01j8…",
    "retryable": false
  }
}
```

A reel whose play count Instagram hides answers with HTTP 200 and `views: null`. The null is part of the answer and bills like any answered request.

## Related

- [Metric semantics](https://openhandle.dev/docs/concepts/metric-semantics): What a view, a like, and a share mean on each platform.
- [Creator payouts use case](https://openhandle.dev/use-cases/creator-payouts): Pay on the platform’s numbers with a capture time on every row.
- [Can I get Instagram like counts when likes are hidden?](https://openhandle.dev/questions/can-i-get-instagram-like-counts-when-likes-are-hidden): Why hidden numbers are null and never zero.