Get Credit History
curl --request GET \
--url https://api.example.com/api/v1/operations/credits/history \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/operations/credits/history"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/operations/credits/history', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/operations/credits/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/operations/credits/history"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/operations/credits/history")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/operations/credits/history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"transactions": [
{
"id": "<string>",
"organizationId": "<string>",
"type": "<string>",
"amount": 123,
"operationType": {},
"source": {},
"referenceId": {},
"description": {},
"metadata": {},
"createdAt": "<string>",
"updatedAt": "<string>"
}
],
"count": 123
}Credits & Payments
Get Credit History
Retrieve the credit transaction history for your organization
GET
/
api
/
v1
/
operations
/
credits
/
history
Get Credit History
curl --request GET \
--url https://api.example.com/api/v1/operations/credits/history \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/operations/credits/history"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/operations/credits/history', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/operations/credits/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/operations/credits/history"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/operations/credits/history")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/operations/credits/history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"transactions": [
{
"id": "<string>",
"organizationId": "<string>",
"type": "<string>",
"amount": 123,
"operationType": {},
"source": {},
"referenceId": {},
"description": {},
"metadata": {},
"createdAt": "<string>",
"updatedAt": "<string>"
}
],
"count": 123
}Overview
Returns a paginated list of credit transactions for the authenticated organization. Transactions include credit additions (from subscriptions, purchases, or bonuses) and credit consumption (from enrichment operations).Authentication
This endpoint requires authentication. The organization ID is automatically
extracted from the authenticated session.
Query Parameters
string
Filter transactions from this date onwards. Must be a valid ISO 8601 date
string. Example:
2025-01-01T00:00:00.000Zstring
Filter transactions up to this date. Must be a valid ISO 8601 date string.
Example:
2025-01-31T23:59:59.999Zinteger
default:"100000"
Maximum number of transactions to return. Must be a positive integer with a
maximum value of 100,000.
integer
default:"0"
Number of transactions to skip for pagination. Must be a non-negative integer.
Response
array
required
Array of credit transaction objects.
Show Transaction Object
Show Transaction Object
string
required
Unique identifier (UUID) for the transaction.
string
required
The organization ID this transaction belongs to.
string
required
The type of transaction. One of: -
credit_added - Credits were added to
the account - credit_consumed - Credits were used for an operation -
adjustment - Manual adjustment to creditsinteger
required
The number of credits involved in this transaction. Always a non-negative
integer.
string | null
For consumption transactions, indicates the operation type: -
enrichment_email - Email enrichment - enrichment_phone -
Phone enrichment - enrichment_combined - Combined email and
phone enrichment - linkedin_enrichment - LinkedIn profile enrichment.
Null for non-consumption transactions.string | null
For credit additions, indicates the source: -
stripe_subscription -
Monthly subscription credits - stripe_purchase - One-time credit
purchase - signup_bonus - Initial signup bonus (250 credits) - manual- Manual credit adjustment Null for consumption transactions.
string | null
External reference ID (e.g., Stripe payment ID) for tracking purposes.
string | null
Human-readable description of the transaction.
object | null
Additional metadata associated with the transaction. For consumption
transactions, may include: -
count - Number of operations performed -
costPerOperation - Credit cost per individual operationstring
required
ISO 8601 timestamp of when the transaction was created.
string
required
ISO 8601 timestamp of when the transaction was last updated.
integer
required
The number of transactions returned in this response.
Example Request
curl -X GET "https://app.lance.so/api/v1/operations/credits/history?limit=10&offset=0" \
-H "Authorization: Bearer YOUR_TOKEN"
const response = await fetch(
"/api/v1/operations/credits/history?limit=10&startDate=2025-01-01T00:00:00.000Z",
{
headers: {
Authorization: `Bearer ${token}`,
},
}
);
const data = await response.json();
Example Response
{
"transactions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organizationId": "org_abc123",
"type": "credit_consumed",
"amount": 50,
"operationType": "enrichment_email",
"source": null,
"referenceId": null,
"description": "10 x enrichment_email (5 credits each)",
"metadata": {
"count": 10,
"costPerOperation": 5
},
"createdAt": "2025-01-13T10:30:00.000Z",
"updatedAt": "2025-01-13T10:30:00.000Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"organizationId": "org_abc123",
"type": "credit_added",
"amount": 1000,
"operationType": null,
"source": "stripe_subscription",
"referenceId": "sub_1234567890",
"description": "Monthly subscription credits",
"metadata": null,
"createdAt": "2025-01-01T00:00:00.000Z",
"updatedAt": "2025-01-01T00:00:00.000Z"
}
],
"count": 2
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Organization ID is required"
}
}
Error Codes
| Status | Code | Description |
|---|---|---|
| 401 | VALIDATION_ERROR | Organization ID is required (user not authenticated) |
| 400 | VALIDATION_ERROR | Invalid query parameters (e.g., invalid date format, limit exceeds 100,000) |
| 500 | INTERNAL_ERROR | An unexpected server error occurred |
Credit Costs Reference
| Operation | Cost (Credits) |
|---|---|
| Email Enrichment | 5 |
| Phone Enrichment | 20 |
| Combined Enrichment | 25 |
| LinkedIn Enrichment | 1 |