GETHashtags1 credit

Top hashtag posts

GET https://api.instagramapi.dev/v1/hashtag/top

Returns the 'Top' posts for a hashtag (Instagram's ranked selection).

Build this with an AI agent

Paste this prompt into Claude, Codex, or any coding agent.

Parameters

Name	Type	Required	Description
tag	string	yes	Hashtag without the `#`.
cursor	string	no	Pagination cursor returned as `next_cursor` in the previous response. Omit for the first page.

Example request

curl "https://api.instagramapi.dev/v1/hashtag/top?tag=sunset" \
  -H "Authorization: Bearer $INSTAGRAMAPI_KEY"

const res = await fetch("https://api.instagramapi.dev/v1/hashtag/top?tag=sunset", {
  headers: { Authorization: `Bearer ${process.env.INSTAGRAMAPI_KEY}` },
});

res = requests.get("https://api.instagramapi.dev/v1/hashtag/top?tag=sunset",
    headers={"Authorization": f"Bearer {INSTAGRAMAPI_KEY}"})

Try it

Live request · uses 1 credit

API key

tag *string

cursorstring

Example responses

Switch tabs to see the body shape for success and each error status.

{
  "data": {
    "items": [
      {
        "id": "3912183471120209303",
        "shortcode": "DZK3iOsRlWX",
        "type": "photo",
        "product_type": "feed",
        "url": "https://www.instagram.com/p/DZK3iOsRlWX/",
        "caption": "Golden hour 🌅 #sunset",
        "taken_at": "2026-06-04T15:59:27Z",
        "like_count": 2499414,
        "comment_count": 55165,
        "view_count": null,
        "image_url": "https://instagram.com/.../media.jpg",
        "video_url": null,
        "video_duration": null,
        "location": null,
        "author": {
          "id": "8472",
          "username": "wanderlust",
          "full_name": "Wanderlust",
          "is_verified": true,
          "is_private": false,
          "profile_pic_url": "https://instagram.com/.../nike.jpg"
        }
      }
    ],
    "next_cursor": "WyJlNmFmZmIz..."
  },
  "meta": {
    "endpoint": "hashtag/top",
    "request_id": "req_3f8a1c9e",
    "credits_charged": 1,
    "credits_remaining": 4987,
    "ms": 412
  }
}

{
  "error": {
    "code": "missing_parameter",
    "message": "Missing required parameter \"tag\".",
    "docs": "/docs/hashtag/top"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid or has been revoked.",
    "docs": "/docs#authentication"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "insufficient_credits",
    "message": "You're out of credits. Top up to continue.",
    "docs": "/dashboard/billing"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "No public data for that request (private, deleted, or nonexistent). This is a billed request. We queried Instagram on your behalf.",
    "docs": "/docs/hashtag/top"
  },
  "meta": {
    "request_id": "req_3f8a1c9e",
    "endpoint": "hashtag/top",
    "credits_charged": 1,
    "credits_remaining": 4985
  }
}

{
  "error": {
    "code": "upstream_error",
    "message": "Upstream data provider error. You were not charged. Please retry.",
    "docs": "/docs/hashtag/top"
  },
  "meta": {
    "request_id": "req_3f8a1c9e"
  }
}

Response fields

Fields returned under data on a 200 response. Every response also includes a meta object with billing info.

Field	Type	Description
items	array<object>	The hashtag's top-ranked posts.
items[].id	string	Numeric post/media id.
items[].shortcode	string	The post's shortcode, the part after /p/ in its instagram.com URL.
items[].type	string	Media type: photo, video, or carousel.
items[].product_type	string	More specific format (e.g. feed, clips, igtv).
items[].url	string	Canonical instagram.com URL for the post.
items[].caption	string	The post's caption text.
items[].taken_at	string	When the post was published (ISO 8601, UTC).
items[].like_count	number	Number of likes.
items[].comment_count	number	Number of comments.
items[].view_count	null	View count for video/reel content; null for photos.
items[].image_url	string	URL of the post's image (cover frame for video).
items[].video_url	null	URL of the video file; null for photos.
items[].video_duration	null	Video length in seconds; null for photos.
items[].location	null	Place tagged on the post, if any; null otherwise.
items[].author	object	The account that published the post.
items[].author.id	string	Numeric account id (stable even if the username changes).
items[].author.username	string	The account's @handle.
items[].author.full_name	string	Display name shown on the profile (may be empty).
items[].author.is_verified	boolean	Whether the account has a verified badge.
items[].author.is_private	boolean	Whether the account is private.
items[].author.profile_pic_url	string	URL of the account's profile picture.
next_cursor	string	Pass back as `cursor` to fetch the next page; null when there are no more results.

Pagination

List endpoints return up to one page of items plus a next_cursor. To fetch the next page, pass it back as the cursor query parameter. When next_cursor is null, you've reached the end.