Billing & Credits

Catalyzed uses a credit-based billing system. Credits are consumed by various operations and tracked at the team level.

How Credits Work

• Each team has a credit balance tracked in nanodollars (for precision)
• Operations consume credits based on resource usage
• When credits are depleted, operations may be blocked
• Credits can be purchased or allocated by plan

Credit-Consuming Operations

Operation	Credit Cost
Query execution	Based on data scanned
Data storage	Per GB per month
File processing	Based on file size
Pipeline execution	Based on compute time
AI model usage	Based on tokens

Checking Credit Balance

Get credit balance

cURL

curl "https://api.catalyzed.ai/teams/ZkoDMyjZZsXo4VAO_nJLk/credits/balance" \
  -H "Authorization: Bearer $API_TOKEN"

TypeScript

const response = await fetch(
  "https://api.catalyzed.ai/teams/ZkoDMyjZZsXo4VAO_nJLk/credits/balance",
  { headers: { Authorization: `Bearer ${apiToken}` } }
);
const credits = await response.json();

Python

response = requests.get(
    "https://api.catalyzed.ai/teams/ZkoDMyjZZsXo4VAO_nJLk/credits/balance",
    headers={"Authorization": f"Bearer {api_token}"}
)
credits = response.json()

Response:

{
  "teamId": "ZkoDMyjZZsXo4VAO_nJLk",
  "balanceNanodollars": 8500000000,
  "balanceUsd": 8.50,
  "totalCreditsNanodollars": 10000000000,
  "totalCreditsUsd": 10.00,
  "totalUsageCostNanodollars": 1500000000,
  "totalUsageCostUsd": 1.50,
  "hasSufficientFunds": true
}

The response provides both nanodollar (precise) and USD (human-readable) values for convenience.

Credit Ledger

View credit transactions with the ledger endpoint:

List credit ledger entries

cURL

curl "https://api.catalyzed.ai/teams/ZkoDMyjZZsXo4VAO_nJLk/credits/ledger?limit=50&offset=0" \
  -H "Authorization: Bearer $API_TOKEN"

TypeScript

const response = await fetch(
  "https://api.catalyzed.ai/teams/ZkoDMyjZZsXo4VAO_nJLk/credits/ledger?limit=50&offset=0",
  { headers: { Authorization: `Bearer ${apiToken}` } }
);
const { entries, total, limit, offset } = await response.json();

Python

response = requests.get(
    "https://api.catalyzed.ai/teams/ZkoDMyjZZsXo4VAO_nJLk/credits/ledger",
    params={"limit": 50, "offset": 0},
    headers={"Authorization": f"Bearer {api_token}"}
)
data = response.json()
entries = data["entries"]

Response:

{
  "entries": [
    {
      "teamCreditLedgerId": "pQqghNlazy2Yxil4OKQcv",
      "teamId": "ZkoDMyjZZsXo4VAO_nJLk",
      "entryType": "usage",
      "amountNanodollars": -150000000,
      "amountUsd": -0.15,
      "description": "Query execution",
      "metadata": null,
      "createdBy": "usr_abc123",
      "createdAt": "2024-01-15T14:30:00Z",
      "idempotencyKey": null
    },
    {
      "teamCreditLedgerId": "zk3PnrrwUDWk_HWXQilsX",
      "teamId": "ZkoDMyjZZsXo4VAO_nJLk",
      "entryType": "credit",
      "amountNanodollars": 10000000000,
      "amountUsd": 10.00,
      "description": "Monthly allocation",
      "metadata": null,
      "createdBy": null,
      "createdAt": "2024-01-01T00:00:00Z",
      "idempotencyKey": null
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

Filter Ledger Entries

# Filter by entry type
curl "https://api.catalyzed.ai/teams/ZkoDMyjZZsXo4VAO_nJLk/credits/ledger?entryType=usage"

# Filter by date range
curl "https://api.catalyzed.ai/teams/ZkoDMyjZZsXo4VAO_nJLk/credits/ledger?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z"

Entry Types

Entry Type	Description
credit	Credits added (purchase, allocation, bonus)
usage	Credits consumed by operations
adjustment	Manual adjustment by support
refund	Credits returned for failed operations

Billing in the App

The Catalyzed app provides a billing dashboard:

1. Navigate to Team Settings
2. Select the Billing tab

You’ll see:

• Credit Balance - Current credits remaining (USD)
• Total Usage - Credits used this billing period
• Ledger - Transaction history
• Usage Breakdown - By operation type

Handling Low Credits

Check Before Operations

For credit-intensive operations, check balance first:

async function checkCreditsAndQuery(sql: string, tableName: string, tableId: string) {
  // Check credits
  const creditsResponse = await fetch(
    `https://api.catalyzed.ai/teams/${teamId}/credits/balance`,
    { headers: { Authorization: `Bearer ${apiToken}` } }
  );
  const credits = await creditsResponse.json();

  if (!credits.hasSufficientFunds) {
    throw new Error("Insufficient credits. Please add more credits.");
  }

  // Execute query
  const queryResponse = await fetch("https://api.catalyzed.ai/queries", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sql,
      tables: { [tableName]: tableId },
    }),
  });

  return queryResponse.json();
}

Insufficient Credits Error

When credits are depleted, you’ll receive a 402 Payment Required response:

{
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS"
}

Cost Optimization Tips

1. Optimize Queries

• Use LIMIT to reduce data returned
• Select only needed columns (avoid SELECT *)
• Add WHERE clauses to filter early
• Create indexes on frequently filtered columns

2. Use Appropriate Storage

• Use Parquet format for large datasets (more efficient)
• Delete unused tables and files
• Archive old data you don’t need to query

3. Batch Operations

• Combine multiple small inserts into batch inserts
• Group related queries together

4. Monitor Usage

Regularly review the credit ledger to identify:

• Unexpected high-cost operations
• Inefficient queries
• Unused resources

Credit Alerts

Set up alerts for low credit balance in the app:

1. Go to Team Settings > Billing
2. Click Configure Alerts
3. Set threshold (e.g., alert when balance below $10)
4. Choose notification method (email, webhook)

FAQs

What happens when credits run out?

Operations that consume credits will fail with a 402 error and INSUFFICIENT_CREDITS code. Read operations (listing, getting) continue to work.

Do unused credits roll over?

Depends on your plan. Free tier credits do not roll over. Paid plans may have rollover options.

Can I get a refund for failed operations?

Credits are automatically refunded for operations that fail due to system errors. User errors (invalid SQL, etc.) are not refunded.

How are query costs calculated?

Query costs are based on:

• Data scanned (bytes read from storage)
• Compute time (execution duration)
• Result size (bytes returned)

Next Steps

• Teams - Team management and settings
• Querying Data - Optimize query costs