SocialAPIs
Sources
PricingBlogFAQContact
Back to Sources

Auto Top-Up Usage

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

Social APIsAvailableusagetop-upsbilling

Ready to try this API?

Edit parameters and send a live request from your browser

Introduction

The Usage Top-Ups API returns your auto top-up configuration, recent top-up history (last 20 charges), and lifetime spend summary. 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 audit auto top-up charges, build billing dashboards, or detect when a top-up has been paused due to a payment failure.

What does this API return?

  • ✅ Auto top-up settings (enabled, threshold, package, payment method)
  • ✅ Last 20 top-up charges (success + failures)
  • ✅ Lifetime credits topped up and total spend
  • ✅ Failure information (pause reason, last failure date)
  • ✅ Rolling spend trackers (today, this month)

Input options

This endpoint takes no body parameters. Authentication is via the

bash
1x-api-token
header.

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

Output example

json
1{
2  "autoTopUp": {  
3    "enabled": true,  
4    "threshold": 500,  
5    "packageSlug": "pro-small",  
6    "packageStripePriceId": "price_1TVrL52NYoBE1MUG1rxuRwkK",  
7    "paymentMethod": {  
8      "brand": "visa",  
9      "last4": "4242"  
10    },  
11    "pausedDueToFailure": false,  
12    "lastTriggeredAt": "2026-05-09T14:23:11.000Z",  
13    "lastSuccessAt": "2026-05-09T14:23:11.000Z",  
14    "lastFailureAt": null,  
15    "lastFailureReason": null,  
16    "spend": {  
17      "spentToday": 599,  
18      "spentThisMonth": 1198  
19    }  
20  },  
21  "summary": {  
22    "totalCreditsToppedUp": 4000,  
23    "totalSpentCents": 1198,  
24    "successfulTopUps": 2,  
25    "totalAttempts": 2  
26  },  
27  "recentHistory": [  
28    {  
29      "date": "2026-05-09T14:23:11.000Z",  
30      "creditsAdded": 2000,  
31      "amountCents": 599,  
32      "packageSlug": "pro-small",  
33      "status": "succeeded",  
34      "failureReason": null,  
35      "trigger": "auto",  
36      "paymentIntentId": "pi_3TVrL52NYoBE1MUG0xABCDEF"  
37    }  
38  ]  
39}

Field reference

bash
1autotopup
object

FieldTypeDescription
enabledbooleanWhether auto top-up is turned on
thresholdintegerTrigger top-up when remaining credits drop below this
packageSlugstringSlug of the selected top-up package
paymentMethodobjectCard brand and last 4 digits (or null)
pausedDueToFailurebooleanTrue if a charge failed and user hasn't re-enabled
lastTriggeredAtstring (ISO date)Last time the top-up worker tried to charge
lastSuccessAtstring (ISO date)Last successful auto top-up
lastFailureAtstring (ISO date)Last failed auto top-up
lastFailureReasonstringDescription of the last failure
spend.spentTodayintegerCents charged today via auto top-up
spend.spentThisMonthintegerCents charged this month via auto top-up

bash
1summary
object

FieldTypeDescription
totalCreditsToppedUpintegerLifetime credits added via top-ups
totalSpentCentsintegerLifetime cents spent on top-ups
successfulTopUpsintegerCount of successful top-ups
totalAttemptsintegerTotal attempts (success + failure)

bash
1recenthistory
array (each entry)

FieldTypeDescription
datestring (ISO date)When the top-up was attempted
creditsAddedintegerCredits granted (0 for failed)
amountCentsintegerAmount charged in cents
packageSlugstringTop-up package used
statusstringsucceeded / failed / requires_action / canceled
failureReasonstringFailure description (null on success)
triggerstringauto / manual / retry
paymentIntentIdstringStripe Payment Intent ID

Rate limit

60 requests per minute per API token. Exceeding this returns

bash
1429 Too Many Requests
.

Conclusion

Use this endpoint to give your customers transparency into their top-up history, build internal billing dashboards, or programmatically detect payment failures that require action.

About the Auto Top-Up Usage API

The Auto Top-Up Usage endpoint is part of SocialAPIs' unified REST API for public social-media data. Get auto top-up settings, recent history (last 20 charges), and lifetime spend summary. 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.

usagetop-upsbillinghistoryfree

What you can do with this endpoint

The Auto Top-Up 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 a unified 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/top-ups" \
  -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 Auto Top-Up Usage. Most real-world integrations combine 2-3 of them.

Plan Limits

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

Account Usage

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

Frequently asked questions

Do I need to register a Facebook app or go through OAuth to use the Auto Top-Up Usage endpoint?

No. SocialAPIs handles the upstream auth and infrastructure on our side. You just send a bearer token (your SocialAPIs API token) and call the endpoint. No Facebook app review, no OAuth scope dance, no expiring user access tokens. This is the primary reason most teams move off the Graph API to us.

How much does a single call to this endpoint cost in credits?

One credit per successful response. The exact cost is shown in the dashboard under "Usage" after every call. Failed requests (4xx errors caused by bad input) do not consume credits.

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. The exception is the Ads Library endpoints, which return Meta's own snapshots and therefore lag by 24-48 hours because Meta itself indexes them on that cadence (not us).

Can I use this endpoint inside Claude Desktop, ChatGPT, or another AI agent?

Yes. The SocialAPIs MCP server exposes every endpoint as an MCP tool, so any MCP-aware client (Claude Desktop, the ChatGPT Custom Integrations beta, Cursor, Cline) can call it directly inside a chat. The MCP server uses the same API token as direct HTTP calls, so your credit balance, rate limits, and usage history are unified across surfaces.

What happens if my call fails or returns an unexpected shape?

Every response — success or error — 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 (params, upstream response, timing, error trace) within minutes. We retain the log for 30 days on standard plans and indefinitely on enterprise. Don't ship a workaround for an edge case without checking with us first — it's usually a two-line server fix.

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 Auto Top-Up 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