Nodium Screenshot API -- Credits

How the credit system works, what each operation costs, and how to manage your usage.

Base URL: https://api.nodium.io/api/v1/screenshot

Table of Contents

• How Credits Work
• Credit Costs by Operation
• Extra Charges
• Plans & Monthly Allowances
• Checking Your Balance
• Credit Exhaustion
• Tips for Optimizing Usage

How Credits Work

Every Nodium account has a monthly credit allowance determined by your plan. Each API request consumes one or more credits depending on the type of operation. Credits reset at the beginning of each billing cycle.

Key points:

• Credits are deducted after a successful response is generated.
• Failed requests (4xx/5xx errors) do not consume credits.
• Cached responses are served at zero credit cost.
• Credits cannot be rolled over to the next billing period.

Credit Costs by Operation

Examples:

• A single PNG screenshot of example.com costs 1 credit.
• A full-page JPEG capture costs 2 credits.
• A bulk request with 25 URLs costs 25 credits (1 per item).
• An animated MP4 recording costs 3 credits.
• Requesting a URL that is already cached costs 0 credits.

Extra Charges

Certain add-on features consume additional credits on top of the base operation cost.

These charges stack with the base cost. For example, a standard screenshot with AI analysis and metadata extraction costs 1 + 2 + 1 = 4 credits.

Plans & Monthly Allowances

Note: Overage charges apply only to paid plans. Free plan requests are rejected once the allowance is exhausted. Enterprise plans can negotiate custom overage rates and volume discounts. Annual billing gives you 2 months free.

Checking Your Balance

Usage endpoint

Send a GET request to /usage to retrieve your current credit balance and usage statistics.

curl "https://api.nodium.io/api/v1/screenshot/usage" \
  -H "X-Access-Key: YOUR_API_KEY"

Response:

{
  "credits_used": 4230,
  "credits_remaining": 770,
  "credits_total": 5000,
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-03-31T23:59:59Z"
}

See the Usage API documentation for full details.

Response headers

Every API response includes a header with your remaining balance:

x-nodium-credits-remaining: 770

This header is present on all successful responses, including cached ones, so you can monitor your balance without making a separate API call.

Credit Exhaustion

When your credits run out, the API returns a 402 Payment Required response:

{
  "error_code": "credits_exhausted",
  "message": "Your monthly credit allowance has been exhausted. Upgrade your plan or wait for the next billing cycle.",
  "http_status_code": 402
}

Behavior by plan:

Tip: Set up notifications to receive an alert when you reach 80% of your monthly allowance. This gives you time to adjust usage or upgrade your plan before running out.

Tips for Optimizing Usage

1. Enable caching

Cached responses cost 0 credits. If you capture the same URL repeatedly, enable caching with a TTL that fits your needs:

curl -X POST "https://api.nodium.io/api/v1/screenshot/take" \
  -H "X-Access-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "cache": true,
    "cache_ttl": 86400
  }' -o screenshot.png

A cache_ttl of 86400 keeps the result cached for 24 hours. Subsequent requests for the same URL and parameters within that window consume zero credits.

2. Use webhooks for async jobs

For large or slow pages, use async mode with webhooks instead of long-polling. This avoids timeout-related retries that consume extra credits:

{
  "url": "https://example.com/heavy-page",
  "format": "png",
  "async": true,
  "webhook_url": "https://yourapp.com/webhook"
}

3. Choose the right format

• Use standard screenshots (1 credit) when you do not need the full page.
• Avoid full_page=true (2 credits) unless you genuinely need the entire scrollable area.
• Reserve animated captures (3 credits) for cases where a static image is insufficient.

4. Batch with bulk requests

The /bulk endpoint costs 1 credit per item but avoids the overhead of individual HTTP requests. Group related captures into a single bulk call when possible.

5. Skip add-ons you do not need

Only enable ai_analysis, extract_metadata, or custom storage when you actually need them. Each adds to the credit cost of every request.

6. Monitor usage regularly

Use the /usage endpoint or the x-nodium-credits-remaining response header to track consumption. Build alerts into your application to pause non-critical captures when credits run low.

Next Steps

• Usage API -- Detailed usage and daily statistics endpoint
• Notifications -- Set up credit warnings and usage alerts
• API Reference -- Complete parameter reference