Account & Usage

The Account API lets you retrieve your account information and monitor your current API usage. Use these endpoints to track your screenshot quota and build usage dashboards.

Get Account Info

GET /api/v1/account

Returns your account details including current plan, subscription status, and API limits.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://screenshotrun.com/api/v1/account

Response

{
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "plan": {
      "name": "Pro",
      "slug": "pro",
      "screenshots_per_month": 10000,
      "rate_limit_per_minute": 60
    },
    "subscription": {
      "status": "active",
      "current_period_end": "2026-04-09T00:00:00.000000Z"
    }
  }
}

Response Fields

Field	Type	Description
`id`	integer	Your user account ID
`name`	string	Your account name
`email`	string	Your account email
`plan`	object\|null	Current plan details (null if on free plan without explicit plan)
`plan.name`	string	Plan display name
`plan.slug`	string	Plan identifier
`plan.screenshots_per_month`	integer	Maximum screenshots allowed per billing period
`plan.rate_limit_per_minute`	integer	Maximum API requests per minute
`subscription`	object\|null	Active subscription details (null if no subscription)
`subscription.status`	string	Subscription status: `active`, `cancelled`, `past_due`, `trialing`, `paused`
`subscription.current_period_end`	string	End date of the current billing period (ISO 8601)

Get Usage Statistics

GET /api/v1/account/usage

Returns your usage statistics for the current billing period, including screenshot counts and remaining quota.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://screenshotrun.com/api/v1/account/usage

Response

{
  "data": {
    "screenshots_used": 3450,
    "screenshots_limit": 10000,
    "screenshots_remaining": 6550,
    "usage_percentage": 34.5,
    "period_start": "2026-03-09T00:00:00.000000Z",
    "period_end": "2026-04-09T00:00:00.000000Z",
    "days_remaining": 27,
    "avg_daily_usage": 115,
    "projected_usage": 4035
  }
}

Response Fields

Field	Type	Description
`screenshots_used`	integer	Number of screenshots taken in the current period
`screenshots_limit`	integer	Maximum screenshots allowed in this period
`screenshots_remaining`	integer	Remaining screenshot quota
`usage_percentage`	float	Percentage of quota used (0–100)
`period_start`	string	Start of the current billing period (ISO 8601)
`period_end`	string	End of the current billing period (ISO 8601)
`days_remaining`	integer	Days remaining in the current billing period
`avg_daily_usage`	integer	Average screenshots per day in the current period
`projected_usage`	integer	Projected total screenshots by end of period based on current pace

Code Examples

PHP — Usage monitoring

$response = Http::withToken(env('SCREENSHOT_API_KEY'))
    ->get('https://screenshotrun.com/api/v1/account/usage');

$usage = $response->json('data');

echo "Used: {$usage['screenshots_used']}/{$usage['screenshots_limit']}";
echo "Remaining: {$usage['screenshots_remaining']}";

// Alert if usage exceeds 80%
if ($usage['usage_percentage'] > 80) {
    Log::warning('Screenshot API usage above 80%', $usage);
}

Python — Usage check before capture

import requests
import os

API_KEY = os.environ["SCREENSHOT_API_KEY"]
BASE_URL = "https://screenshotrun.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Check remaining quota before taking screenshots
usage = requests.get(f"{BASE_URL}/account/usage", headers=headers).json()["data"]

if usage["screenshots_remaining"] > 0:
    response = requests.post(
        f"{BASE_URL}/screenshots",
        headers=headers,
        json={"url": "https://example.com"}
    )
    print(f"Screenshot created! Remaining: {usage['screenshots_remaining'] - 1}")
else:
    print(f"Quota exceeded! Resets at: {usage['period_end']}")

JavaScript — Account dashboard widget

async function getUsageSummary() {
  const [accountRes, usageRes] = await Promise.all([
    fetch("https://screenshotrun.com/api/v1/account", {
      headers: { Authorization: `Bearer ${API_KEY}` },
    }),
    fetch("https://screenshotrun.com/api/v1/account/usage", {
      headers: { Authorization: `Bearer ${API_KEY}` },
    }),
  ]);

  const account = (await accountRes.json()).data;
  const usage = (await usageRes.json()).data;

  return {
    plan: account.plan?.name ?? "Free",
    used: usage.screenshots_used,
    limit: usage.screenshots_limit,
    percentage: usage.usage_percentage,
    renewsAt: usage.period_end,
    subscriptionStatus: account.subscription?.status ?? "none",
  };
}

// Example output:
// { plan: "Pro", used: 3450, limit: 10000, percentage: 34.5, ... }

Usage Alerts

We automatically send notifications when your usage reaches certain thresholds:

Threshold	Action
80% of monthly quota	Warning notification sent to your account email
90% of monthly quota	Second warning notification sent to your account email
100% of monthly quota	API returns `402 USAGE_LIMIT_EXCEEDED` for new screenshot requests

To increase your quota, upgrade your plan at any time. The new limits take effect immediately.

Subscription Statuses

Status	Description	API access
`active`	Subscription is active and in good standing	Full access
`trialing`	Subscription is in trial period	Full access
`cancelled`	Subscription cancelled but still within the paid period	Full access until period end
`past_due`	Payment failed, awaiting retry	Limited access
`paused`	Subscription paused by user	Read-only access