All questionsInstagram

How do I get Instagram Reel play counts?

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.

Checked September 2026 · request and response run against the API · no affiliate links

Get started for $0 Quickstart

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

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

TypeScript SDK

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

{
  "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 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

404 Not Found

{
  "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.

Send your agent ahead.

Paste the prompt into your agent and it sets everything up. Or come yourself, it takes five minutes.

For agents

Get started for $0 Read the quickstart