The easiest mistake in a traffic dashboard happens after the request succeeds: an old snapshot is labeled as today’s traffic, or a missing value becomes zero. Keep the response’s meaning attached to the number from the first request. This example shows the request, the fields to retain and how to handle an incomplete batch.
Make one request before building a batch
Create an API key in your Vaneform account and place it in the VANEFORM_API_KEY environment variable in your own terminal or server. With curl available, the command below reads the cached scale family for google.com. It follows the normal account point rules. The environment check stops the command when the key is missing; keep the key out of browser code and shared examples.
Inspect the outer resource status and scale.status before using scale.visits. Save your own retrieval timestamp separately from scale.month and scale.as_of. A successful request may return a partial or missing snapshot, so inspect the value before adding it to a chart.
curl --silent --show-error --fail-with-body --max-time 30 \
--header "Authorization: Bearer ${VANEFORM_API_KEY:?Set VANEFORM_API_KEY}" \
"https://vaneform.com/api/v1/domains/google.com/scale"The fields that protect a traffic comparison
Vaneform’s public scale resource uses the fields below. This guide describes the contract reviewed on October 8, 2026; the API documentation remains the place to check current endpoints and access rules. Public responses expose the product’s estimate lane, so a client should use that field instead of assuming an internal data supplier identifier will be available.
- scale.estimate: site or search, identifying the kind of estimate.
- scale.visits: the estimated visit value when available.
- scale.month and scale.as_of: the supplied reporting month and observation date.
- scale.confidence: the supplied qualitative confidence label.
- scale.status: the state of the traffic family, inspected alongside the resource status.
- scale.monthly_visits: the available month-and-visits series; retain each point’s month.
A synthetic scale fragment, with its context intact
This JSON is an invented excerpt from the scale object, not a live lookup or the complete response envelope. It demonstrates the fields a comparison row needs. A request to GET /api/v1/domains/example.com/scale reads the scale family through the authenticated API; follow the linked API documentation for key setup and the complete response shape.
The value 42,000 describes September in this example even if your job reads it during October. “medium” stays a qualitative label. Assigning it a made-up probability, such as 70%, would introduce a claim the response never supplied.
{
"status": "ready",
"estimate": "site",
"visits": 42000,
"month": "2026-09",
"as_of": "2026-09-30",
"confidence": "medium"
}Missing observations change the denominator
Suppose an invented three-domain batch returns 42,000 visits, 18,000 visits and one missing value. The usable observations total 60,000, with an observed-domain average of 30,000 across two domains. Report coverage as two of three. Substituting zero for the missing value produces an average of 20,000 and conceals the coverage gap.
For a trend chart, use an explicit gap for a missing month. If you display the last available observation, keep its original month visible. A dashboard can remain useful while showing incomplete coverage, and a later observation can fill the gap without rewriting what was known at the earlier review.
Ratios and limits deserve their own checks
Vaneform’s scale.sources channel values are proportions: 0.25 renders as 25%. Keep that unit separate from percentage-change fields such as visits_mom_change_pct. A report that multiplies a percentage change by 100 again will distort the movement even if the underlying visit counts are correct.
At the review date, Free accounts include 100 points per UTC month for ordinary API domain reads; keyword lookup, keyword rankings and include=search require Pro. A cached data read can still be subject to account usage rules. Use the documentation’s account and error information to plan a bounded job, and preserve request identifiers for investigating failures.
Handle the error code before retrying
For a 401 unauthorized or invalid_api_key response, correct the credential. A 403 search_requires_pro or pro_required response requires the matching plan or a request without that capability. Repeating either request unchanged will not resolve it.
A 429 needs the body’s error.code: credits_exhausted and lookup_limit_exceeded mean waiting for the relevant allowance to reset or resolving the account allowance; lookup_rate_exceeded means pacing requests, honoring Retry-After when supplied. Bound temporary-error retries and retain error.request_id for diagnosis. This prevents an incomplete batch from turning into an uncontrolled retry loop.
For a resumed batch, record which domains already produced a usable observation and which failed with a retryable condition. Keep the successful snapshot’s original period and status. Before repeating the batch, review the outstanding rows and the remaining allowance, then retry only the work still needed. This reduces accidental duplicate work while preserving a clear distinction between a stored observation and an attempt that returned no usable metric.