Billing

Credits are the unit of consumption for the Pharlo. Every publish operation deducts credits from your organization's balance. Use this endpoint to check the current balance, your active plan, and how many credits have been used in the current billing cycle.

To obtain an API key, see Authentication. For a full explanation of plans and credit pricing, see the Billing & Credits guide.

Base URL: https://pharlo.io
Auth: Authorization: Bearer ds_live_...

Endpoints

Method	Path	Description	Status
GET	`/api/v1/billing/status`	Current balance and plan	200

`GET /api/v1/billing/status`

Returns the current credit balance, active plan, and billing cycle info for your organization.

This endpoint does not consume credits. Use it freely for monitoring dashboards or pre-flight balance checks before submitting assignments.

Example request

curl https://pharlo.io/api/v1/billing/status \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response `200 OK`

{
  "balance": 1250,
  "plan": "growth",
  "planName": "Growth",
  "monthlyCredits": 2000,
  "creditsUsedThisCycle": 750,
  "cycleStartedAt": "2026-04-01T00:00:00Z",
  "cycleResetsAt": "2026-05-01T00:00:00Z"
}

Response fields

Field	Type	Description
`balance`	int	Remaining credits available for new operations.
`plan`	string	Machine-readable plan identifier (e.g. `growth`, `starter`, `enterprise`).
`planName`	string	Human-readable plan name.
`monthlyCredits`	int	Total credits allocated per billing cycle on the current plan.
`creditsUsedThisCycle`	int	Credits consumed since `cycleStartedAt`.
`cycleStartedAt`	ISO 8601	When the current billing cycle began (UTC).
`cycleResetsAt`	ISO 8601	When the balance resets for the next cycle (UTC). Unused credits do not roll over.

⚠️

Unused credits do not roll over between cycles. If your balance is low before cycleResetsAt, consider holding non-urgent assignments until the cycle resets. To upgrade your plan, contact your organization admin or see the Billing & Credits guide.

Response headers on billable requests

Every API request that consumes credits returns these headers alongside the normal response. You can use them for real-time balance tracking without calling the status endpoint separately.

Header	Description
`X-Credits-Used`	Credits consumed by this specific request.
`X-Credits-Balance`	Remaining balance after this request was processed.
`X-Credits-Required`	Credits needed for the operation (only present on `402` responses).

Example — reading credit headers

# -i prints response headers
curl -i -X POST https://pharlo.io/api/v1/assignments \
  -H "Authorization: Bearer $DELIVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connectionId": "...", "type": "video", "payload": {...}}'
 
# Response headers will include:
# X-Credits-Used: 3
# X-Credits-Balance: 1247

`402 Payment Required`

Returned when your credit balance is insufficient to complete the requested operation. The X-Credits-Required header tells you exactly how many credits are needed. No credits are deducted on a 402 response.

HTTP/1.1 402 Payment Required
X-Credits-Required: 3
X-Credits-Balance: 1
 
{"error": "Insufficient credits", "required": 3, "balance": 1}

Example — handling 402 in code

import requests
 
response = requests.post(
    "https://pharlo.io/api/v1/assignments",
    headers={"Authorization": "Bearer ds_live_your_key_here", "Content-Type": "application/json"},
    json={"connectionId": "...", "type": "video", "payload": {}},
)
 
if response.status_code == 402:
    required = response.headers.get("X-Credits-Required")
    balance = response.headers.get("X-Credits-Balance")
    print(f"Insufficient credits. Need {required}, have {balance}. Top up and retry.")
else:
    response.raise_for_status()
    print("Assignment created:", response.json()["id"])

⚠️

Top up credits via the console or contact your organization admin. There is no automatic retry — your application must catch 402 and queue the request until sufficient balance is available.

Error responses

Status	Reason
`401`	Missing or invalid API key. See Authentication.
`403`	API key does not have permission to read billing info for this organization.

{"error": "Unauthorized", "message": "Invalid or missing API key."}

For a full guide on error handling and retries, see Error Handling.