> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sociavault.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Credits Balance
> Returns the current credit balance and subscription status for the authenticated user
Returns the current credit balance and subscription status for the authenticated user.
## Reading the response
`subscriptionStatus` is `free` on every new account and becomes `active` once a credit pack is
purchased. `free` is not an error and does not mean credits are missing — an account can sit on
`free` with a healthy balance from its signup credits.
`subscriptionId` holds the Stripe **Checkout Session** ID of the most recent purchase (`cs_...`),
not a Stripe subscription ID. Credit packs are one-time purchases.
## Balance reads 0 and free after paying
This almost always means the request authenticated as a **different account** from the one that
was billed. It is easy to end up with more than one account without realising: signing in with a
different Google identity, or with a work address instead of a personal one, creates a separate
account with its own API key and its own balance.
A purchase credits the account that checked out. It has no effect on keys belonging to any other
account.
To check which account a key belongs to, call this endpoint with that exact key and compare the
balance against the one your dashboard shows:
```bash theme={null}
curl https://api.sociavault.com/v1/credits \
-H "X-API-Key: YOUR_API_KEY"
```
If the two disagree, the key is from another account. Copy the key again from the dashboard of
the account you purchased on, then update it everywhere it is configured — scripts, environment
variables, CI secrets, and the `?apiKey=` query parameter if you use the hosted MCP server.
Keys belong to an account, not to a person. Two accounts owned by the same person do not share
a balance, and regenerating the key on one account does not affect the other.
## Which header to use
API keys go in `X-API-Key`. Sending an `sk_live_...` key as `Authorization: Bearer` returns
`401`, because the `Bearer` scheme is reserved for dashboard session tokens.
```bash theme={null}
# correct
curl https://api.sociavault.com/v1/credits -H "X-API-Key: sk_live_..."
# returns 401
curl https://api.sociavault.com/v1/credits -H "Authorization: Bearer sk_live_..."
```
The two failure codes mean different things. A `402` means the request authenticated fine and
was stopped at the credit check, so the key itself is valid. A `401` means the key was not
accepted at all.
## OpenAPI
````yaml GET /v1/credits
openapi: 3.1.0
info:
title: SociaVault API
version: 1.0.0
description: >-
# SociaVault API Documentation
The SociaVault API provides comprehensive access to social media data
extraction across multiple platforms.
## Features
- **Multi-Platform Support**: TikTok, Instagram, YouTube, Facebook, Twitter,
Reddit, Threads, and more
- **Credit-Based System**: Pay-as-you-go pricing with transparent credit
costs
- **High Performance**: Fast, reliable data extraction
- **Comprehensive Data**: Detailed user profiles, videos, posts, comments,
and analytics
## Authentication
All API requests require authentication using an API key in the `X-API-Key`
header:
```bash
X-API-Key: sk_live_your_api_key_here
```
Get your API key from the [SociaVault
Dashboard](https://sociavault.com/dashboard).
## Credits
Each endpoint consumes credits based on data complexity:
- Simple requests (profiles): 1 credit
- Complex requests (demographics): 20+ credits
- Paginated requests: Credits per page
Check your credit balance in the dashboard or via the API.
## Support
- **Documentation**: https://docs.sociavault.com
- **Email**: support@sociavault.com
- **Discord**: https://discord.gg/sociavault
contact:
name: SociaVault Support
email: support@sociavault.com
url: https://sociavault.com/support
license:
name: Commercial
url: https://sociavault.com/terms
servers:
- url: https://api.sociavault.com
description: Production API
security:
- ApiKeyAuth: []
tags:
- name: account
description: Account management and credit balance
externalDocs:
description: Learn more
url: https://docs.sociavault.com/account
- name: tiktok
description: Scrape TikTok profiles, videos, and more
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/tiktok
- name: tiktok-shop
description: Everything about TikTok Shop
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/tiktok-shop
- name: instagram
description: Gets Instagram profiles, posts, and reels
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/instagram
- name: youtube
description: Scrape YouTube channels, videos, and more
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/youtube
- name: linkedin
description: Scrape LinkedIn
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/linkedin
- name: facebook
description: Get public Facebook profiles and posts
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/facebook
- name: facebookAdLibrary
description: Scrapes the Facebook (Meta) Ad Library
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/facebookAdLibrary
- name: facebookMarketplace
description: Search Facebook Marketplace and pull full listing details
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/facebookMarketplace
- name: googleAdLibrary
description: >-
Scrape the Google Ad Transparency Library. *This only gets the public ads.
Some ads you need to log in for and sadly we can't get those. Also, since
there are so many variations, the return types might not all be 100% the
same.
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/googleAdLibrary
- name: linkedinAdLibrary
description: Search the LinkedIn Ad Library
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/linkedinAdLibrary
- name: twitter
description: Get Twitter profiles, tweets, followers and more
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/twitter
- name: reddit
description: Scrape Reddit posts and comments
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/reddit
- name: threads
description: Get Threads posts
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/threads
- name: google
description: Scrape Google search results
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/google
paths:
/v1/credits:
get:
tags:
- account
summary: Get Credits Balance
description: >-
Returns the current credit balance and subscription status for the
authenticated user
operationId: get_credits
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
credits:
type: integer
description: Remaining credits available
example: 950
subscriptionStatus:
type: string
description: >-
Billing state of the account. `free` is the default for
every new account, including accounts that still hold
their signup credits, and remains the value until a credit
pack is purchased. `active` means a credit pack has been
purchased on this account. These are the only two values
the API returns.
example: active
enum:
- free
- active
subscriptionId:
type: string
description: >-
Stripe Checkout Session ID of the most recent credit pack
purchase, or null if there has not been one. Despite the
field name this is a checkout session (cs_...), not a
Stripe subscription - credit packs are one-time purchases.
example: >-
cs_live_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2w3X4y5Z6
nullable: true
required:
- credits
- subscriptionStatus
examples:
purchased:
summary: Credit pack purchased
value:
credits: 5994
subscriptionStatus: active
subscriptionId: >-
cs_live_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2w3X4y5Z6
signupCredits:
summary: New account, signup credits only
value:
credits: 50
subscriptionStatus: free
subscriptionId: null
depleted:
summary: >-
Free account with nothing left - every scrape call returns
402. If you have purchased a pack and still see this, the
key belongs to a different account than the one that was
billed.
value:
credits: 0
subscriptionStatus: free
subscriptionId: null
'401':
description: Unauthorized - Invalid or missing API key
'404':
description: User not found
'500':
description: Server error
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: |-
API key for authentication. Format: `sk_live_xxxxxxxxxxxxx`
Get your API key from the [Dashboard](https://sociavault.com/dashboard).
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.