# GET /v1/download: Reels and TikTok downloader

The files of one post by its link: an Instagram post, reel or IGTV, or a TikTok video or photo post (short links too). The video (TikTok's without the watermark), every picture of a carousel or photo post, the cover and, for TikTok, the soundtrack and caption. Files only, no metrics: use post or tiktok/video for those. File links are temporary: download right away.

- Call: `GET https://storiesfly.com/api/v1/download`
- Price **a fixed price: $0.20 per 1,000 for a TikTok link, $0.50 per 1,000 for an Instagram link**
- Answers up to **15 minutes** old

## Parameters

All parameters go in the query string.

| Name | Type | Sent | Description |
| --- | --- | --- | --- |
| `url` | string | required | An Instagram post, reel or IGTV link, or a TikTok video or photo link (short links too). |

## Example request

Put your own key in the header, or in the apiKey option of the npm client.

### cURL

```bash
curl "https://storiesfly.com/api/v1/download?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FDdY3MUJCfby%2F" \
  -H "X-Api-Key: sf_live_your_key"
```

### JavaScript

```javascript
const res = await fetch(
  "https://storiesfly.com/api/v1/download?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FDdY3MUJCfby%2F",
  { 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/download",
    params={"url": "https://www.instagram.com/p/DdY3MUJCfby/"},
    headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]},
)
data = r.json()
```

## Example response

200 OK · X-Units-Charged: 1

```json
{
  "platform": "instagram",
  "id": "DdY3MUJCfby",
  "url": "https://www.instagram.com/p/DdY3MUJCfby/",
  "author": "arianagrande",
  "caption": null,
  "media_type": "video",
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.82787-15/813966136_18783396925039697_6406007525826130925_n.jpg",
  "media": [
    {
      "type": "video",
      "url": "https://instagram.fbeg3-2.fna.fbcdn.net/o1/v/t2/f2/m86/AQPHnjf83HZ9PR2G28elI5BWiebhxAmJxbUPxxIecjIu2AxjcEHA6WoTngqdgKKomsQIGeIYxUjVgFzMRcMB4yqxuvGRfQCLsvGsZV8.…",
      "quality": null,
      "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.82787-15/813966136_18783396925039697_6406007525826130925_n.jpg"
    }
  ],
  "audio_url": null
}
```

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

## Price and freshness

A call is sold at a fixed price: $0.20 per 1,000 for a TikTok link, $0.50 per 1,000 for an Instagram link, the same at every level. It uses one free request while you have them, then your balance.

Answers are kept for up to 15 minutes. Asking again inside that time returns the same answer and is charged again.

## 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 post does not exist, is private or was removed. Charged like an answer. |
| `429` | `rate_limited` | More requests in a second than your level allows, more than this group can take at once, or more than 1,000 TikTok and download calls today. 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 it cost?

A fixed price, the same at every level: $0.20 per 1,000 for a TikTok link, $0.50 per 1,000 for an Instagram link. While you have free requests, a call uses one of them instead.

### Which links can I send?

An Instagram post, reel or IGTV link, or a TikTok video or photo link, the short share links included. A profile, story or share link of Instagram is refused with `bad_request`.

### Why are there no views or likes?

It returns files only, no metrics. For the numbers, call [post](https://storiesfly.com/developers/docs/post) or [tiktok/video](https://storiesfly.com/developers/docs/tiktok-video).

## Related endpoints

- [GET /v1/tiktok/video](https://storiesfly.com/developers/docs/tiktok-video): One TikTok video without the watermark, with views, likes, comments and shares
- [GET /v1/post](https://storiesfly.com/developers/docs/post): One post: media links, caption, views, likes, comments, shares, saves and reposts
- [GET /v1/resolve](https://storiesfly.com/developers/docs/resolve): Turn a post, reel or share link into data

## Links

- [This page on the site](https://storiesfly.com/developers/docs/download)
- [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