NodiumNodium
ScreenshotOG ImageIntegrationsPricingDocsSign inGet started

Nodium Screenshot API -- Usage & Statistics

Retrieve credit usage, screenshot counts, and daily breakdowns through the usage API.

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

Table of Contents

GET /usage

Returns your current billing period summary.

GET https://api.nodium.io/api/v1/screenshot/usage

Response

json
{
  "credits_used": 12450,
  "credits_remaining": 12550,
  "credits_total": 25000,
  "screenshots_taken": 9870,
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-03-31T23:59:59Z",
  "breakdown": {
    "screenshot": { "count": 8200, "credits": 8200 },
    "full_page": { "count": 650, "credits": 1300 },
    "pdf": { "count": 420, "credits": 840 },
    "video": { "count": 200, "credits": 600 },
    "bulk_items": { "count": 400, "credits": 400 },
    "add_ons": { "ai_analysis": 310, "metadata": 500, "custom_storage": 300 }
  }
}

Response Fields

FieldTypeDescription
credits_usedintegerTotal credits consumed this billing period
credits_remainingintegerCredits still available
credits_totalintegerTotal credit allowance for the period
screenshots_takenintegerTotal number of capture operations
period_startstring (ISO 8601)Start of current billing period
period_endstring (ISO 8601)End of current billing period
breakdownobjectUsage broken down by operation type
breakdown.add_onsobjectCredits consumed by add-on features

Breakdown by Type

The breakdown object splits usage into operation categories:

CategoryDescriptionCredits per Operation
screenshotStandard screenshots via /take1
full_pageFull-page screenshots (full_page=true)2
pdfPDF generation (format=pdf)2
videoAnimated captures via /animate3
bulk_itemsIndividual items in /bulk requests1

The add_ons object tracks extra credits consumed by optional features:

Add-onDescription
ai_analysisCredits from AI Vision analysis requests
metadataCredits from metadata extraction requests
custom_storageCredits from custom storage uploads

GET /usage/daily

Returns an array of daily usage statistics for the current billing period.

GET https://api.nodium.io/api/v1/screenshot/usage/daily

Response

json
{
  "daily": [
    {
      "date": "2026-03-01",
      "credits_used": 420,
      "screenshots_taken": 380,
      "breakdown": { "screenshot": 310, "full_page": 30, "pdf": 15, "video": 10, "bulk_items": 15 }
    },
    {
      "date": "2026-03-02",
      "credits_used": 510,
      "screenshots_taken": 460,
      "breakdown": { "screenshot": 390, "full_page": 35, "pdf": 12, "video": 8, "bulk_items": 15 }
    }
  ],
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-03-31T23:59:59Z"
}

Each entry in the daily array contains the same breakdown fields, scoped to a single calendar day (UTC).

Filtering by Date Range

Both /usage and /usage/daily accept optional date range parameters:

ParameterTypeDescription
start_datestring (YYYY-MM-DD)Start of the date range (inclusive)
end_datestring (YYYY-MM-DD)End of the date range (inclusive)
bash
curl "https://api.nodium.io/api/v1/screenshot/usage/daily?start_date=2026-03-01&end_date=2026-03-07" \
  -H "X-Access-Key: YOUR_API_KEY"
Note: Date range cannot exceed 90 days. If omitted, the current billing period is used.

Response Headers

Every API response (not just usage endpoints) includes credit information in the headers:

HeaderDescriptionExample
x-nodium-credits-remainingCredits left in current period12550
x-nodium-credits-usedTotal credits used in current period12450

These headers allow you to monitor your balance passively without calling the /usage endpoint. Parse them in your application to trigger warnings or throttle requests when credits run low.

Code Examples

cURL

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

# Daily breakdown for the first week of March
curl "https://api.nodium.io/api/v1/screenshot/usage/daily?start_date=2026-03-01&end_date=2026-03-07" \
  -H "X-Access-Key: YOUR_API_KEY"

Node.js (fetch)

javascript
async function getUsage() {
  const response = await fetch(
    "https://api.nodium.io/api/v1/screenshot/usage",
    {
      headers: { "X-Access-Key": "YOUR_API_KEY" },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.error_code}: ${error.message}`);
  }

  const usage = await response.json();
  console.log(`Credits: ${usage.credits_used} / ${usage.credits_total}`);
  console.log(`Remaining: ${usage.credits_remaining}`);
  console.log(`Screenshots taken: ${usage.screenshots_taken}`);

  return usage;
}

getUsage();

Python (requests)

python
import requests

response = requests.get(
    "https://api.nodium.io/api/v1/screenshot/usage",
    headers={"X-Access-Key": "YOUR_API_KEY"},
)

if response.status_code == 200:
    usage = response.json()
    print(f"Credits: {usage['credits_used']} / {usage['credits_total']}")
    print(f"Remaining: {usage['credits_remaining']}")
else:
    error = response.json()
    print(f"Error: {error['error_code']} - {error['message']}")

Monitoring Integration

Prometheus / Grafana

Expose credits as a Prometheus gauge by polling the /usage endpoint:

python
from prometheus_client import Gauge

credits_remaining = Gauge("nodium_credits_remaining", "Nodium credits remaining")
credits_used = Gauge("nodium_credits_used", "Nodium credits used this period")

def update_metrics():
    usage = requests.get(
        "https://api.nodium.io/api/v1/screenshot/usage",
        headers={"X-Access-Key": "YOUR_API_KEY"},
    ).json()
    credits_remaining.set(usage["credits_remaining"])
    credits_used.set(usage["credits_used"])

For real-time monitoring without polling, parse the x-nodium-credits-remaining header in your application middleware and emit metrics on every screenshot request. This works with any monitoring backend (Datadog, New Relic, CloudWatch).

Next Steps

  • Credits -- Understand credit costs and plan allowances
  • Notifications -- Configure automated alerts for credit thresholds
  • API Reference -- Complete endpoint and parameter reference