Credit Usage

Query credit usage history for your project, broken down by profile, integration, or platform.

Endpoint

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

Returns monthly credit history for your project. Without filters it returns project-level totals. Scope it 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

Parameter	Type	Required	Description
`profileId`	string	No	Scope to a specific profile. Mutually exclusive with `integrationId`.
`integrationId`	string	No	Scope to a specific connected account (integration). Mutually exclusive with `profileId`.
`from`	string	No	Inclusive start month (`YYYY-MM`). Filters the usage history array.
`to`	string	No	Inclusive end month (`YYYY-MM`). Filters the usage history array.

Usage Modes

Mode 1: Project-level totals

No filters — returns the full credit history for the project.

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

{
	"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 }
		}
	]
}

totalUsage is the all-time total. usage is the monthly history, oldest first. platform shows how many credits went to each platform that month — it will be empty for months before platform tracking was enabled.

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"

{
	"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"

{
	"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"

{
	"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

Field	Type	Description
`totalUsage`	integer	All-time credits used (unfiltered)
`usage`	array	Monthly history, oldest first
`usage[].year`	integer	Calendar year
`usage[].month`	integer	Calendar month (1–12)
`usage[].count`	integer	Credits used this month
`usage[].platform`	object	Credits per platform name this month

Status Codes

Code	Meaning
`200`	Success
`400`	Invalid parameters or conflicting filters
`404`	Integration not found (when using `integrationId`)

On this page