Credit Usage

Endpoint

GET https://api.postpeer.dev/v1/usage

Returns monthly credit history and current balance for your project. Without filters it returns project-level totals including a balance field showing exactly how many credits you have left. Scope to a profile or a specific connected account with profileId or integrationId. Each monthly entry includes the total credit count and a per-platform breakdown.

Query Parameters

Usage Modes

Mode 1: Project-level totals

No filters — returns the full credit history for the project plus your current balance.

curl "https://api.postpeer.dev/v1/usage" \
  -H "x-access-key: YOUR_API_KEY"

import PostPeer from '@postpeer/node';

const client = new PostPeer();
const { data } = await client.usage.get();

from postpeer import PostPeer

with PostPeer() as client:
    usage = client.usage.get()

{
	"success": true,
	"totalUsage": 1374,
	"usage": [
		{ "year": 2026, "month": 5, "count": 257, "platform": {} },
		{ "year": 2026, "month": 6, "count": 414, "platform": {} },
		{
			"year": 2026,
			"month": 7,
			"count": 280,
			"platform": { "pinterest": 12, "twitter": 268 }
		}
	],
	"balance": {
		"monthly": {
			"limit": 10000,
			"used": 280,
			"remaining": 9720,
			"cycleStart": "2026-07-02T00:00:00.000Z",
			"cycleEnd": "2026-08-02T00:00:00.000Z"
		},
		"purchased": {
			"total": 1000,
			"used": 0,
			"remaining": 1000
		}
	}
}

totalUsage is the all-time total. usage is the monthly history, oldest first. platform shows how many credits went to each platform that month.

balance reflects real-time credit state — monthly.used combines the billing-cycle total from the database with any credits used today (from cache), so it's always up to date. cycleEnd is when the monthly counter resets. purchased credits never expire and are drawn on automatically once monthly credits run out.

Mode 2: Scoped to a profile

Pass a profileId to see usage for one of your end-user profiles.

curl "https://api.postpeer.dev/v1/usage?profileId=69f76379ce885e092dfa375e" \
  -H "x-access-key: YOUR_API_KEY"

const { data } = await client.usage.get({
	query: { profileId: '69f76379ce885e092dfa375e' },
});

usage = client.usage.get(profile_id="69f76379ce885e092dfa375e")

{
	"success": true,
	"totalUsage": 45,
	"usage": [
		{
			"year": 2026,
			"month": 6,
			"count": 20,
			"platform": { "twitter": 15, "instagram": 5 }
		},
		{
			"year": 2026,
			"month": 7,
			"count": 25,
			"platform": { "twitter": 18, "pinterest": 7 }
		}
	]
}

If the profile has never used any credits, totalUsage is 0 and usage is an empty array.

Mode 3: Scoped to an integration

Pass an integrationId to see usage for a specific connected social account.

curl "https://api.postpeer.dev/v1/usage?integrationId=69da6882322e75b602ad2916" \
  -H "x-access-key: YOUR_API_KEY"

const { data } = await client.usage.get({
	query: { integrationId: '69da6882322e75b602ad2916' },
});

usage = client.usage.get(integration_id="69da6882322e75b602ad2916")

{
	"success": true,
	"totalUsage": 18,
	"usage": [
		{ "year": 2026, "month": 7, "count": 18, "platform": { "twitter": 18 } }
	]
}

Mode 4: Date range filter

Use from and to (both YYYY-MM) to slice the history to a specific window. Works with or without profileId/integrationId.

curl "https://api.postpeer.dev/v1/usage?from=2026-06&to=2026-07" \
  -H "x-access-key: YOUR_API_KEY"

const { data } = await client.usage.get({
	query: { from: '2026-06', to: '2026-07' },
});

usage = client.usage.get(from_="2026-06", to="2026-07")

{
	"success": true,
	"totalUsage": 1374,
	"usage": [
		{ "year": 2026, "month": 6, "count": 414, "platform": {} },
		{
			"year": 2026,
			"month": 7,
			"count": 280,
			"platform": { "pinterest": 12, "twitter": 268 }
		}
	]
}

Note: totalUsage is always the all-time total regardless of the date filter. usage is what gets sliced.

Response Shape

Status Codes