curl -X GET "https://app.lance.so/api/v1/operations/credits/balance" \
-H "Authorization: Bearer <token>"
const response = await fetch("/api/v1/operations/credits/balance", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data = await response.json();
console.log(`Balance: ${data.balance} credits`);
interface CreditBalance {
balance: number;
organizationId: string;
}
const response = await fetch("/api/v1/operations/credits/balance", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data: CreditBalance = await response.json();
{
"balance": 1500,
"organizationId": "org_2abc123def456"
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Organization ID is required"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
Credits & Payments
Get Credits Balance
Retrieve the current credit balance for the authenticated organization
GET
/
api
/
v1
/
operations
/
credits
/
balance
curl -X GET "https://app.lance.so/api/v1/operations/credits/balance" \
-H "Authorization: Bearer <token>"
const response = await fetch("/api/v1/operations/credits/balance", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data = await response.json();
console.log(`Balance: ${data.balance} credits`);
interface CreditBalance {
balance: number;
organizationId: string;
}
const response = await fetch("/api/v1/operations/credits/balance", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data: CreditBalance = await response.json();
{
"balance": 1500,
"organizationId": "org_2abc123def456"
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Organization ID is required"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
This endpoint returns the current credit balance for the organization associated with the authenticated user. Credits are used for various enrichment operations within the platform.
Authentication
This endpoint requires authentication. The organization ID is automatically
determined from the authenticated session.
Request
This endpoint does not require any request parameters. The organization is identified automatically from the authentication context.Response
integer
required
The current credit balance for the organization. This is a non-negative
integer representing the total available credits. Example:
1500string
required
The unique identifier of the organization whose balance was retrieved.
Example:
org_2abc123def456Credit Usage
Credits are consumed when performing enrichment operations:| Operation Type | Description |
|---|---|
enrichment_email | Email address enrichment |
enrichment_phone | Phone number enrichment |
enrichment_combined | Combined email and phone enrichment |
linkedin_enrichment | LinkedIn profile enrichment |
Credit Sources
Credits can be added to an organization through several sources:| Source | Description |
|---|---|
stripe_subscription | Monthly subscription allocation |
stripe_purchase | One-time credit purchase |
signup_bonus | Welcome bonus for new organizations |
manual | Manual credit adjustment by admin |
curl -X GET "https://app.lance.so/api/v1/operations/credits/balance" \
-H "Authorization: Bearer <token>"
const response = await fetch("/api/v1/operations/credits/balance", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data = await response.json();
console.log(`Balance: ${data.balance} credits`);
interface CreditBalance {
balance: number;
organizationId: string;
}
const response = await fetch("/api/v1/operations/credits/balance", {
method: "GET",
headers: {
Authorization: "Bearer <token>",
},
});
const data: CreditBalance = await response.json();
{
"balance": 1500,
"organizationId": "org_2abc123def456"
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Organization ID is required"
}
}
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
400 | VALIDATION_ERROR | User is not authenticated or not associated with an organization |
500 | INTERNAL_ERROR | Server error while retrieving balance |
Notes
- The balance is calculated as the sum of all credit transactions (additions minus consumptions) for the organization
- Balance can be zero but never negative - the system prevents operations that would result in negative balance
- New organizations receive a signup bonus upon first access