Account Usage

Get current credit balance, usage, plan info, and billing period. Free — does not consume credits.

Social APIsAvailableusagecreditsaccount

Ready to try this API?

Edit parameters and send a live request from your browser

Introduction

The Usage API returns your current credit balance, plan information, and billing period. It is free — calls to this endpoint do not consume any credits — and is rate-limited to 60 requests per minute per API token.

Use it to build dashboards, monitor your remaining credits, or detect when you should upgrade your plan or top up.

What does this API return?

✅ Current credit balance (remaining, used, total)
✅ Base + bonus credit breakdown
✅ Usage percentage
✅ Period reset date (resetAt)
✅ Last reset date (lastResetAt)
✅ Plan name, slug, billing interval
✅ Subscription status (active, cancel-at-period-end, custom)

Input options

This endpoint takes no body parameters. Authentication is via the x-api-token header.

bash

1curl https://api.socialapis.io/api/usage \  
2  -H "x-api-token: YOUR_API_TOKEN"

Output example

json

1{
2  "creditsRemaining": 1247,  
3  "creditsUsed": 253,  
4  "creditsLimit": 1500,  
5  "usagePercent": 16.9,  
6  "baseCredits": 1500,  
7  "bonusCredits": 0,  
8  "resetAt": "2026-06-10T11:40:47.000Z",  
9  "lastResetAt": "2026-05-11T11:40:47.000Z",  
10  "plan": {  
11    "slug": "pro",  
12    "name": "SR Pro",  
13    "billingInterval": "month",  
14    "subscriptionActive": true,  
15    "subscriptionType": "stripe",  
16    "cancelAtPeriodEnd": false,  
17    "isCustom": false  
18  }  
19}

Field reference

Field	Type	Description
creditsRemaining	integer	Credits available for use right now
creditsUsed	integer	Credits consumed in the current billing period
creditsLimit	integer	Total credits granted this period (base + bonus)
usagePercent	number	Percentage of credits used (0–100, 1 decimal)
baseCredits	integer	Credits from your subscription plan
bonusCredits	integer	Credits from auto top-ups (carry over)
resetAt	string (ISO date)	When your credits will refresh
lastResetAt	string (ISO date)	When your credits last refreshed
plan.slug	string	Plan identifier (basic, pro, ultra, mega, or prod_… for custom)
plan.name	string	Human-readable plan name
plan.subscriptionActive	boolean	Whether subscription is currently active
plan.cancelAtPeriodEnd	boolean	True if user has scheduled cancellation
plan.isCustom	boolean	True for custom-negotiated plans

Rate limit

60 requests per minute per API token. Exceeding this returns 429 Too Many Requests.

Conclusion

This is the simplest way to monitor your account programmatically. It's safe to poll, free to call, and perfect for usage dashboards, alerts, or upgrade-prompt logic.

About the Account Usage API

The Account Usage endpoint is part of SocialAPIs' REST API for public Facebook and Instagram data. Get current credit balance, usage, plan info, and billing period. Free — does not consume credits. It belongs to the Social APIs category and follows the same auth, pagination, and error-handling conventions as every other endpoint on the platform — so any code you write for one transfers cleanly to the others.

usagecreditsaccountbillingfree

What you can do with this endpoint

The Account Usage endpoint is most often combined with other SocialAPIs endpoints to power the workflows below. Each one is achievable on the Free tier for evaluation; scale up to Pro or Ultra when you move to production.

Building one dataset

Pipe the GET response straight into BigQuery, Postgres, Airtable, or a Google Sheet via n8n / Make / Zapier. The response is structured JSON — no HTML parsing, no headless browser, no upstream OAuth.

Powering an AI agent (MCP)

The same endpoint is exposed as a tool in the SocialAPIs MCP server, so Claude Desktop / ChatGPT custom integrations / Cursor / any MCP-aware client can call it directly inside a chat. No glue code, no separate auth — the user's API token does both.

Scheduled monitoring & alerts

Schedule a recurring call (cron, GitHub Actions, n8n schedule), diff the latest response against the previous run, and notify Slack / email / Telegram when a meaningful change appears. The response shape is stable across calls so diffs stay reliable.

Backfilling a product feature

If you're building a feature on top of public social data (lead enrichment, brand monitoring, competitive intelligence, resale arbitrage), this endpoint usually replaces a brittle in-house scraper that broke every time Facebook tweaked its HTML. Same dataset, real-time, with an SLA.

Working code example

All SocialAPIs endpoints take your API token in the x-api-token header. Grab yours from your dashboard (or create a free account at /auth/signup — 200 free calls per month, no credit card).

curl -X GET "https://api.socialapis.io/usage" \
  -H "x-api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

The response is JSON containing the requested data plus a request_id (echo it back in any support email — it lets us pull the matching row from our request log in seconds). Detailed parameter schemas and copy-paste snippets in JavaScript, Python, PHP, Java, and Go are available in the playground above.

Pagination, rate limits, and error handling

Pagination

List-style endpoints return a next_cursor in the response. Pass it back in the next request to walk the full result set. Cursors are stable across calls — safe to persist if you need to resume later.

Rate limits

1,000 req/hour on the Free tier; paid tiers step up by an order of magnitude each — 1 req/sec on Pro, 5 req/sec on Ultra, 10 req/sec on Mega, 20+ req/sec on custom Enterprise plans. Limit hits return HTTP 429 with a Retry-After header — respect it and you'll never see a sustained block.

Errors

4xx = your request (bad params, missing auth, hit limit). 5xx = our side (transient — retry with backoff). Every error response includes error_code, message, and a request_id for support.

Related endpoints in the Social APIs category

These endpoints share the same data model and auth as Account Usage. Most real-world integrations combine 2-3 of them.

Auto Top-Up Usage

Get auto top-up settings, recent history (last 20 charges), and lifetime spend summary. Free — does not consume credits.

Plan Limits

Get your plan's rate limit, max concurrent tasks, and allowed top-up packages. Free — does not consume credits.

Frequently asked questions

Do I need to register a Facebook app or use OAuth to call the Account Usage endpoint?

No. You only send your SocialAPIs API key in the x-api-token header. We read the public data as a logged-out visitor sees it, with no Facebook account, login or cookies, so there is no Facebook app to register, no OAuth and no access token to renew.

How much does a single call cost in credits?

One credit per call for most endpoints; the price of this endpoint is shown on this page, and a few options cost more (for example the exact follower count). Every response says what it charged in the X-SocialAPIs-Credits-Deducted header. Calls that return data are charged, including empty results; errors (4xx / 5xx, timeouts) are not.

Is the data real-time or cached?

Real-time. Each call fetches from the upstream source at the moment you call us — we don't cache responses between users. Exception: the Ads Library endpoints return Meta's own snapshots, which lag by 24-48 hours because Meta itself indexes them on that cadence.

Can I call this endpoint from Claude Desktop or another AI agent?

Yes. The SocialAPIs MCP server exposes every endpoint as an MCP tool, so any MCP-aware client (Claude Desktop, ChatGPT Custom Integrations, Cursor, Cline) can call it directly inside a chat. Uses the same API token as direct HTTP calls.

What happens if my call fails or returns unexpected data?

Every response includes a request_id in both the body and the x-request-id header. Email it to support and we can pull the full request log within minutes. We retain logs for 30 days on standard plans and indefinitely on enterprise.

Heads up if you're migrating from the Graph API

Some fields Meta's official Graph API used to return are no longer publicly accessible (page email, exact follower counts on small pages, post audience targeting). Where we can derive them from other public signals, we do; where we can't, the field will be absent from the response (we don't fabricate values). The full list of "what's still returnable in 2026" lives in the docs — start there before assuming a field is broken on our side.

Ready to call Account Usage?

Use the playground at the top of this page to send a live request against your account — or grab the curl above and run it from your terminal. Free accounts get 200 calls per month, enough to integrate, prototype, and ship a working demo before deciding whether to upgrade.

Create a free API key · See pricing · Browse all endpoints

Questions about this endpoint