# GET /v1/account: Account and balance API

Your plan, the price of one unit, your balance and free units, the next step of the ladder and your use of the last 30 days by endpoint. Costs nothing.

- Call: `GET https://storiesfly.com/api/v1/account`
- Price **free**
- **Always current**

## Parameters

This endpoint takes no parameters. Send the key and nothing else.

## Example request

Put your own key in the header.

### cURL

```bash
curl "https://storiesfly.com/api/v1/account" \
  -H "X-Api-Key: sf_live_your_key"
```

### JavaScript

```javascript
const res = await fetch(
  "https://storiesfly.com/api/v1/account",
  { 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/account",
    headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]},
)
data = r.json()
```

## Example response

200 OK · X-Units-Charged: 0

```json
{
  "tier": "START",
  "unit_price_usd": 0.0015,
  "balance_usd": 9.238,
  "free_units": 0,
  "lifetime_topup_usd": 10,
  "next_tier": null,
  "tier_cap": "START",
  "usage_30d": [
    {
      "endpoint": "user.profile",
      "calls": 512,
      "spent_usd": 0.618
    },
    {
      "endpoint": "user.posts",
      "calls": 96,
      "spent_usd": 0.144
    }
  ]
}
```

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

## Price and freshness

This call is free. It still counts toward your rate limit.

The answer is always current.

## 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 |
| --- | --- | --- |
| `401` | `unauthorized` | The `X-Api-Key` header is missing or the key is wrong. Free. |
| `403` | `telegram_required` | The account behind the key is not linked to Telegram. The answer has a `link_url` to do it. Free. |
| `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. Free. |

## Questions about this endpoint

### Does this call cost anything?

No. It takes 0 requests, so you can check your balance as often as you like within your rate limit.

### What does it show?

Your level (`tier`), the price of a request, your balance, the free requests you have left, your lifetime top-ups, the next level and what it still needs, and your use in the last 30 days by endpoint.

### Can I use it to test a key?

Yes. A valid key answers with the account, and a wrong or missing key answers `unauthorized` (HTTP 401).

## Related endpoints

- [GET /v1/user/profile](https://storiesfly.com/developers/docs/user-profile): Profile with verified badge, bio, link and counts
- [GET /v1/user/stories](https://storiesfly.com/developers/docs/user-stories): Stories live now, with the length of each video
- [GET /v1/search/users](https://storiesfly.com/developers/docs/search-users): Find accounts by name or username

## Links

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