We're rolling out a major update to the VwD Public API that introduces a flexible, usage-based token model for creator scans, three new endpoints, and richer responses on the endpoints you already use. This post lays out what's changing, what (if anything) will break, and how to migrate before the production cutover.

Status: these changes are live for early integration on QA (https://api.qa.vwd.ai/api/public/v1/). A production rollout date will be announced ahead of cutover.

At a Glance

• Token-based pricing for creator scans, re-scans, and monitoring. Plan-based seat limits no longer govern the API.
• 3 new endpoints for budget discovery, scan catalogs, and re-scanning.
• 3 breaking changes — quota error shape, bulk-create semantics, and an explicit scan_type default. Details below.
• ?dry_run=true lets you preview the token cost and outcome of any billable action without side effects.
• New response fields that surface scan depth, visibility windows, and pipeline state. Additive — safe for existing clients.

Breaking Changes

There is no backward-compatibility shim — these are a hard cutover. Update before the production rollout.

1. Quota errors return 402 Payment Required, not 403 Quota exceeded

Endpoints that previously rejected quota-exhausted requests with 403 now return 402 with a standardized envelope.

Before:

HTTP/1.1 403 Forbidden
{
  "detail": "Quota exceeded",
  "limit": 100,
  "used": 100,
  "remaining": 0,
  "reason_code": "QUOTA_EXCEEDED"
}

After:

HTTP/1.1 402 Payment Required
{
  "type": "client_error",
  "errors": [
    { "code": "insufficient_tokens", "detail": "...", "attr": null }
  ],
  "required": 3,
  "available": 1,
  "is_admin": null
}

The body has three variants keyed by errors[0].code:

What to do: any client branching on 403 Quota exceeded must re-route to 402 and parse the new body shape.

2. Bulk create is all-or-nothing at the budget gate

POST /creators/ with a top-level items array previously created creators up to your remaining allowance and reported per-item "quota_exceeded". It now performs a single up-front budget check: if you cannot afford the whole batch, the entire request returns 402 and nothing is created or charged.

Per-row save failures after the budget gate (rare race conditions, integrity errors) now appear as a new row status:

{ "index": 5, "status": "failed", "errors": { "_": "<server-side message>" } }

Rows with status: "failed" are not charged, and the rest of the batch continues normally.

The top-level quota object and the per-item "quota_exceeded" status have been removed.

What to do: anyone switching on the row status field with a default → error branch should add the new "failed" case alongside "created", "duplicate_requires_confirmation", and "invalid".

3. scan_type is validated, defaults to scan_full

POST /creators/ now accepts and validates a scan_type request field. If omitted, the default is scan_full (3 tokens, full history). Invalid slugs return 400.

POST /creators/
{
  "name": "Jane Doe",
  "social_profiles": [{ "platform": "instagram", "profile_url": "..." }],
  "scan_type": "scan_1y",
  "monitoring": true
}

What to do: clients that previously omitted scan_type will now be charged 3 tokens per creator. Pick a cheaper tier (e.g. scan_1y for 1 token) by passing scan_type explicitly. The authoritative list of valid slugs and costs is GET /scan-catalog/.

What's New

New endpoints

Request features

• ?dry_run=true on POST /creators/ (single and bulk) and POST /creators/{id}/monitor/ previews token cost and outcome without creating anything or debiting tokens. Returns { dry_run, token_cost, available, would_succeed, reason }.
• monitoring: true on POST /creators/ enables monitoring at creation time (+1 token), saving a follow-up call.

Response fields

• deepest_scan — on creator list and search responses. The deepest scan tier your organization has purchased for this creator (null if none).
• scan_statuses[] — on GET /creators/{id}/. Per-scan state, including freshness, pipeline stage, and available re-scan options.
• visibility{} — on GET /creators/{id}/. Declares the date range of historical data visible to your organization for this creator, whether deeper coverage is purchasable, and which scan tier would unlock it.

All additions are backward-compatible; existing clients will ignore them safely.

New Concepts

Prepaid tokens

Billable actions (new scans, re-scans, monitoring) consume tokens from your organization's API budget. Token balance is visible at GET /account/usage/. Token purchasing happens outside the API — contact your account manager.

Scan tiers

A scan tier determines how much of a creator's history is analyzed. Current seeded defaults (admin-configurable; always check GET /scan-catalog/ for live values):

Re-scan tiers (rescan_lite, rescan_mild, rescan_full) follow the same cost structure and refresh an already-added creator. Note that re-scan slugs use the rescan_* namespace — do not pass them where an initial-scan slug is expected.

Data visibility windows

For creators added under the new token model, historical sub-resources (posts, timeline, brands, compliance) are scoped to the time range covered by the scan tier your organization purchased. The visibility{} block on GET /creators/{id}/ tells you the exact range and whether a deeper scan is available. Creators added before this update remain unrestricted.

How to Prepare

1. Audit your error handling for 403 Quota exceeded — re-route to 402 and parse the new envelope.
2. Update bulk-create row-status logic to include "failed" as a non-charging failure case.
3. Choose an explicit default scan_type for your integration so you don't unintentionally pay for scan_full.
4. Adopt ?dry_run=true in any flow that surfaces cost to end users.
5. Wire GET /account/usage/ into your dashboards if you display VwD usage.
6. Test against QA at https://api.qa.vwd.ai/api/public/v1/ before the production cutover.

Questions?

Reach out to support@vwd.ai for early-access keys, migration assistance, or to schedule a walkthrough with our team.