# GET /v1/hashtag/posts: Hashtag posts API

Posts under a hashtag, a page at a time. sort is top (default), recent or reels. Pass next_cursor back as cursor, with the same sort, for the next page.

- Call: `GET https://storiesfly.com/api/v1/hashtag/posts`
- Price **1 request**
- Answers up to **15 minutes** old

## Parameters

All parameters go in the query string.

| Name | Type | Sent | Description |
| --- | --- | --- | --- |
| `name` | string | required | Hashtag, with or without the #. Letters, digits and underscores. |
| `sort` | string | optional | Which posts: top, recent or reels. Top when left out. |
| `cursor` | string | optional | The next_cursor of the page before. Leave it out for the first page. |

## Example request

Put your own key in the header.

### cURL

```bash
curl "https://storiesfly.com/api/v1/hashtag/posts?name=sunset" \
  -H "X-Api-Key: sf_live_your_key"
```

### JavaScript

```javascript
const res = await fetch(
  "https://storiesfly.com/api/v1/hashtag/posts?name=sunset",
  { headers: { "X-Api-Key": process.env.STORIESFLY_KEY } }
);
const data = await res.json();
```

### Python

```python
import os
import requests

r = requests.get(
    "https://storiesfly.com/api/v1/hashtag/posts",
    params={"name": "sunset"},
    headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]},
)
data = r.json()
```

## Example response

200 OK · X-Units-Charged: 1

```json
{
  "name": "sunset",
  "sort": "top",
  "posts": [
    {
      "id": "4008759724161160248",
      "shortcode": "Deh-brUhNQ4",
      "url": "https://www.instagram.com/reel/Deh-brUhNQ4/",
      "owner": {
        "id": "599856410",
        "username": "diariodagrazy"
      },
      "taken_at": 1792101520,
      "taken_at_iso": "2026-10-15T21:58:40.000Z",
      "caption": "E nessas curvas que você se perde ....",
      "media_type": "reel",
      "pinned": false,
      "thumbnail_url": "https://scontent-sea5-1.cdninstagram.com/v/t51.71878-15/851829779_1770583013990215_835716211381604570_n.jpg",
      "media": [
        {
          "id": "4008759724161160248",
          "type": "video",
          "image_url": "https://scontent-sea5-1.cdninstagram.com/v/t51.71878-15/851829779_1770583013990215_835716211381604570_n.jpg",
          "video_url": "https://scontent-sea5-1.cdninstagram.com/o1/v/t2/f2/m86/AQP0Sz4ySoZQjh4BV91pgVydMhbTkDhspKz8cCMaanWDIOm2zWLj-SKbuscyzel4YGkPuZgW9yHQVPVDp5qLN2s070NbV1nUSuf2vZg…",
          "width": 1080,
          "height": 1920,
          "video_duration": 7.012
        }
      ],
      "likes": 287,
      "comments": 11,
      "shares": 9,
      "reposts": 2,
      "views": 14731,
      "saves": 62,
      "video_duration": 7.012,
      "counts_hidden": false
    },
    {
      "id": "4008916553093152070",
      "shortcode": "DeiiF1pTP1G",
      "url": "https://www.instagram.com/reel/DeiiF1pTP1G/",
      "owner": {
        "id": "78263752112",
        "username": "halikar_1234_"
      },
      "taken_at": 1792120157,
      "taken_at_iso": "2026-10-16T03:09:17.000Z",
      "caption": "#kannada #sunset #karunadaraitha #loveyourself #ootd",
      "media_type": "reel",
      "pinned": false,
      "thumbnail_url": "https://scontent-sea5-1.cdninstagram.com/v/t51.71878-15/850988769_1576531443779323_6357846782779890581_n.jpg",
      "media": [
        {
          "id": "4008916553093152070",
          "type": "video",
          "image_url": "https://scontent-sea5-1.cdninstagram.com/v/t51.71878-15/850988769_1576531443779323_6357846782779890581_n.jpg",
          "video_url": "https://scontent-sea5-1.cdninstagram.com/o1/v/t2/f2/m86/AQNJs-FhWyVrGeRRVI81Gjdjm0-rLXG904i0ml_fyzq_WS5G02eoffEVVF5d_-wZouUcgDiHjs8W29AErB3Y7cj_tRdJ7NGkzRhR7n4…",
          "width": 1080,
          "height": 1920,
          "video_duration": 26.308
        }
      ],
      "likes": 865,
      "comments": 3,
      "shares": 36,
      "reposts": 6,
      "views": 11091,
      "saves": 8,
      "video_duration": 26.308,
      "counts_hidden": false
    }
  ],
  "next_cursor": "c1.ryg6VkAgkE2BcPyGM0q6ADwLG1KAGWvXyxXcleap6rtdnm6USXXD4rRRujLUjticHxS2vixe2jbdlG4LggGvIE1ISp6sYLXI6XWcb66UIrM_RMPDKCUhQylnCgNoMsPrfzM",
  "has_more": true
}
```

A real answer, shortened: lists are cut to two items and long texts to 160 characters.

## Price and freshness

A call takes 1 request. Free requests are spent first, then your balance. The [pricing](https://storiesfly.com/developers/pricing) page has the rates.

Answers are kept for up to 15 minutes. Asking again inside that time returns the same answer and takes 1 request again.

Page size follows Instagram and varies by endpoint.

## Errors

A failed call answers with an HTTP status and a body `{error, code}`. These are the codes this endpoint gives. [Errors and what is charged](https://storiesfly.com/developers/docs#errors) covers all of them.

| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | A parameter is missing or wrong. `fields` lists the names. Free. |
| `401` | `unauthorized` | The `X-Api-Key` header is missing or the key is wrong. Free. |
| `402` | `credits_exhausted` | The free requests and the balance are used up. Top up in the [dashboard](https://storiesfly.com/developers/dashboard). Free. |
| `403` | `telegram_required` | The account behind the key is not linked to Telegram. The answer has a `link_url` to do it. Free. |
| `404` | `not_found` | The hashtag does not exist. Charged like an answer. |
| `429` | `rate_limited` | More requests in a second than your level allows. Wait for the `Retry-After` header. Free. |
| `500` | `internal_error` | A fault on our side. Retry shortly. Refunded. |
| `503` | `upstream_unavailable` | Our side failed or timed out. Retry shortly. Refunded. |

## Questions about this endpoint

### What does sort do?

`sort` is `top` (the default), `recent` or `reels`. `top` and `recent` list posts, `reels` lists reels.

### How do I get the next page?

Send the `next_cursor` back as `cursor`, with the same `sort`: a cursor of one sort is refused with another. Each page takes 1 request.

### What does each post hold?

The same fields as [user/posts](https://storiesfly.com/developers/docs/user-posts): caption, media, time, the owner and the counts.

## Related endpoints

- [GET /v1/hashtag](https://storiesfly.com/developers/docs/hashtag): A hashtag with its post count
- [GET /v1/search/hashtags](https://storiesfly.com/developers/docs/search-hashtags): Find hashtags, with their post counts
- [GET /v1/search/top](https://storiesfly.com/developers/docs/search-top): The top posts for a text
- [GET /v1/location/posts](https://storiesfly.com/developers/docs/location-posts): Posts tagged at a place: top or recent

## Links

- [This page on the site](https://storiesfly.com/developers/docs/hashtag-posts)
- [Instagram data API](https://storiesfly.com/developers): what the API is and what it returns
- [Pricing](https://storiesfly.com/developers/pricing): rates, examples and billing rules
- [Documentation](https://storiesfly.com/developers/docs): quick start, authentication, errors and every endpoint
- [OpenAPI file](https://storiesfly.com/openapi.json): the whole API in one file
- [API dashboard](https://storiesfly.com/developers/dashboard): get a key and top up
- [Changelog](https://storiesfly.com/developers/changelog): what changed and when