Use the right key
Both keys belong to your Wildcard account. Store them as secrets in your own site-builder backend. Neither key belongs in a customer’s page or tracking snippet.
Send the appropriate key in
X-API-Key. A management key does not authenticate
visitor-data requests; a data key does not manage domains. All examples below use
https://api-v1.maverickintelligence.co.
Page traffic: people and AI agents
UseGET /v1/traffic/pages for page views by URL, including anonymous human
visitors, AI requests, and a breakdown by agent. It uses the same data key and
customer domain groups as the visitor APIs.
data row has a domain and normalized path, with:
human.pageViews: human-classified page loads, including unidentified visitors.human.uniqueVisitorsandhuman.sessions: distinct recorded visitor and session IDs. Missing IDs are disclosed inpageViewsWithoutVisitorIdandpageViewsWithoutSessionId; they are never invented from IP addresses.ai.requestsandai.byAgent: server-observed AI page requests, with stable agent IDs such asopenai-crawler,openai-crawler-user,anthropic-crawler, andperplexity-crawler.ai.pageViewsis the subset with a confirmed successful HTML response. A request-time hook can count visits without claiming that the later response succeeded.- With
include_people=true,identifiedPeoplecontains matched person IDs, names and company names.human.identifiedPageViewsandhuman.unidentifiedPageViewspartition the human count. Identification uses explicit browser identities and currently visible person records; it does not run enrichment. Unmatched or conflicting identities stay unidentified. Use/v1/people/{id}for the full identified profile.
totals covers every matching page, even when the response is paginated.
Unique visitors and sessions in totals are deduplicated across pages, so do
not sum page-level unique counts. A repeat page load is another page view;
it may belong to the same session and visitor.
Use measure to read only what you need. measure=human returns human
counts (and identifiedPeople with include_people=true) without reading
server AI observations; measure=ai returns AI agent counts without reading
human data. Fields belonging to the part you did not request are omitted, not
zeroed. The default, measure=all, returns both, as before. Splitting reads is
much faster for accounts that send server traffic, for example humans and
people every 15 minutes and AI agents hourly.
Filters: domain (exact hostname), domain_group_id, client_ref, path
(exact normalized path), agent (exact returned AI agent ID), since, and
until. These filters intersect with the key’s scope; an apex filter never
includes a separately tracked subdomain. agent returns only matching
server AI traffic. Query strings, fragments and trailing slashes do not create
different pages. Different hostnames remain separate.
The default window is the last seven days. Supply timezone-aware ISO timestamps;
since is inclusive and until is exclusive, with a maximum 31-day window.
Use limit=1..1000 (default 100) and repeat every filter with
pagination.nextCursor as cursor. Pagination pins the time window. Follow-up
batches requested within five minutes usually reuse the first batch’s result,
so rows do not shift between batches; if it is no longer available, the batch
is recomputed and late arriving events can change results. This is a live
report, not a frozen export: for final numbers, query windows that ended a few
minutes ago. Every successful
response has meta.complete=true. If a window exceeds the bounded read or
identity budget, the API returns 422 window_too_large with no partial totals.
Query shorter windows (daily if necessary). Identity lookup is capped at 100
distinct explicit email identities per request.
If the query exceeds its processing deadline, the API returns
503 query_timeout with a Retry-After: 30 header; wait at least that
long, then retry with a smaller window.
Collect AI requests from the server
The browser pixel provides human page activity. Crawlers that never execute JavaScript need a server/edge collector. Install this on the actual website request path; a script tag alone does not provide complete crawler coverage. Submit page observations toPOST /v1/traffic/events using a
server-held, preferably domain-scoped data key. Keep the original request
User-Agent. For response observations, include the actual successful response
status and HTML content type. Do not submit assets, API calls,
prefetch requests, redirects, failures, raw IPs, cookies or emails.
observationType: "request"
and omit statusCode and contentType. These count toward ai.requests, not
confirmed ai.pageViews. Only report actual page-route GETs; exclude prefetches,
assets and API routes. The default observationType: "response" requires a
successful HTML response. Choose one observation type per request, not both.
Send 1–100 events per batch. Timestamps must be within the past seven days
(up to five minutes of forward clock skew). 202 returns accepted and
duplicates counts. Retries must reuse the same event ID, timestamp and
payload. Changing a previously used ID/timestamp payload returns 409.
A batch interrupted after some writes can be retried in full. This endpoint
records traffic only; it does not invoke providers, paid enrichment or delivery.
Paused, held, archived, unregistered and out-of-scope sites cannot submit traffic.
The downloadable server collector
works with standard Request/Response objects. Call recordPageResponse
after obtaining the actual response and keep its promise alive with your
server platform’s background-task mechanism. For example, a Cloudflare Worker:
src/proxy.ts), use recordPageRequest
inside the existing page-route handler after redirect checks. This does not
need another proxy or a change to the page response:
Retry-After on
429. The existing 1,000 requests/hour data API limit includes collection.
Coverage and interpretation
Human counts default to browser observations.human_source=server selects
server-observed human page loads instead; it never adds the two sources.
Optional server visitorId/sessionId values must be opaque first-party IDs;
without them server unique visitor/session counts remain zero with missing-ID
counts reported. Identity matching is available for browser observations only.
AI request totals use server observations. browserAiPageViews separately exposes AI
observations made by the browser pixel, without double-counting them against
server requests. Other bots and unclassified requests have separate fields for
each source. meta.coverage reports observations and their most recent timestamp;
aiCoverage=server_collection_not_observed means zero AI traffic is not
evidence that no AI agents visited. Verify the collector on each installed site.
Agent names are User-Agent claims, not verified operator identities.
Human classification is a browser heuristic after known automation is excluded.
Spoofed User-Agents and agents indistinguishable from normal browsers remain
limitations. A human referral from ChatGPT is human traffic, not an AI visit.
Browser blockers, consent, installation coverage and data retention affect
observed totals. Server collection begins when installed; it cannot recreate
past crawler requests that were never collected.
1. Create one group per customer
For example, a customer with ten sites can have one group namedAcme. Choose a
stable groupId from your own system so a retry does not create another group.
IDs are case-sensitive, 1–64 letters, numbers, underscores, or hyphens, beginning
with a letter or number. Names are 1–100 characters.
{ "success": true, "group": { "groupId": "acme", "name": "Acme", "domains": [], "createdAt": "...", "updatedAt": "..." } }.
Creation returns 201; retrying with the same ID and name returns 200.
Omit domains in this creation call so retries preserve sites attached later.
A different payload for an existing ID returns 409; use PATCH to change it.
Omit groupId only if you want Wildcard to generate an ID.
2. Register each new site and install its snippet
Call this from your backend whenever your site builder provisions a domain:domain, customerId, pixelSnippet, status, and
trackingSyncPending. Install the returned pixelSnippet in your site’s shared
page template. Every site under your partner account uses the same partner
customerId; a domain or group ID is not a new Wildcard customer ID. Use the
returned snippet rather than constructing a different account ID per site.
groupId is optional. Supplying it attaches the newly registered site—or an
existing site you already own—to that group. The group must exist first. A
clientRef is a separate optional label for attribution; it does not create a group.
Check GET /v1/partner/domains for the site’s status. Tracking is ready when the
site is active and trackingSyncPending is false. Registration does not override
an explicitly paused site or inactive account. Retry a 429 with backoff and
jitter. Inspect other errors before retrying; a conflict or limit failure needs
attention. A partial registration can be retried with the same domain and group.
The domain list returns maxDomains, your account’s configured site limit. Groups
organize that allowance; creating a group does not increase it. A site can belong
to more than one group. Keep both API keys on your backend—the browser snippet
uses your account identifier without exposing either key.
3. Read visitors for a group
Use your data key, withdomain_group_id in the query string:
www.
aliases. Add subdomains explicitly if they are separate sites. An apex member
such as example.com does not implicitly add news.example.com to that group.
A visitor matches if they have visited a member site.
You can combine domain_group_id with domain or client_ref. These constraints
intersect: one matching visit must satisfy them all, and an API key’s domain
scope remains a hard limit. Groups are filters, not additional permissions.
An empty group returns no visitors; a missing group or a group belonging to
another partner returns 404; a malformed group ID returns 400.
List responses contain data and pagination. Keep the same filters and pass
pagination.nextCursor as cursor until there is no next cursor. A filtered page
may be empty while another cursor remains. Membership is read again on every
request, so deleting or emptying a group never falls back to your entire account.
/v1/people/{id}/events?domain_group_id=acme. Filtering the people list does not
implicitly filter a later events request; send the group on both.
Who was identified in a time window
To ask “who was identified on our sites between X and Y, and which pages did they view?”, addvisited_since (and optionally visited_until, default now) to
/v1/people. Only people with at least one identified page view in that window
are returned. Add include_page_views=true to get those page views on each
person (timestamp, url, pageTitle, domain), oldest first, up to 200 per
person (pageViewsTruncated says when more exist).
- Timestamps need a timezone;
visited_untilis exclusive; a window is at most 31 days. limitgoes up to 250 in this mode. Followpagination.nextCursoruntil it is absent; a page can hold fewer thanlimitpeople while a cursor remains.- Results are ordered by when each person’s record last changed, not by visit
time. A person updated while you page can appear again on a later page;
deduplicate by
id. Nobody is skipped. - Identifications can arrive after the visit, so re-reading a recent window can return more people. Re-read recent windows rather than treating them as final.
- This covers people identified by Wildcard’s visitor identification. People
identified only through your own identify calls appear in
/v1/traffic/pages?include_people=true. - The existing filters (
domain,client_ref,domain_group_id, key scope,hot_leads_only,email_status,path,since) still apply. Page views are limited to the same sites.
Maintain groups
GET /v1/partner/domain-groupsreturns{ "groups": [...] }for your account.PATCH /v1/partner/domain-groupsacceptsgroupIdplusnameand/ordomains. Thedomainsarray replaces membership and may contain only sites already tracked by your partner account. An empty array empties the group.DELETE /v1/partner/domain-groupsaccepts{ "groupId": "acme" }. It removes the group without deleting sites or visitor history.
Attribution on every record
People and events both carry the client they belong to:domain or client_ref:
domain matches subdomains too — acme.com includes app.acme.com. If a client
has several domains registered under one clientRef, client_ref covers them all.
Giving a client direct access
Rather than relaying data through your own product, you can issue each client an API key scoped to their domain only. In the dashboard, go to Partner → Domains and select Enable API on a client’s domain. The key is shown once. It behaves like any other API key, with one difference: it can only ever read that one client’s data./v1/peoplereturns only that client’s visitors./v1/people/{id}/eventsreturns only events from that client’s domain.- Another client’s person ID returns
404, not an empty result — a scoped key cannot confirm that visitors outside its scope exist. - Passing
?domain=for someone else’s domain returns nothing. The scope is a ceiling, not a default.
Reading a journey
A journey is the ordered stream of everything a visitor did:cursor rather than assuming you got everything in one
response.
Event shape is open-ended. eventId, sessionId, eventType, timestamp and
url are always present. Everything else depends on the event type, and new event
types and fields appear as the tracking pixel evolves — without an API version
change. Treat eventType as an open set and ignore fields you do not recognise
rather than rejecting the payload.
Narrow to one kind of step with event_type:
Getting journeys pushed instead of polled
If you’d rather receive activity than fetch it, subscribe to theperson.activity event on your partner webhook (Partner → Partner Webhook).
This event is opt-in. It is far higher volume than person.identified — one
engaged visitor fires dozens of events — so it is off by default and you must
switch it on deliberately.
Deliveries are batched per visitor: you get one call carrying that person’s
new events as an array, not one call per event.
truncated is true — page the
API for the complete journey rather than assuming the batch is whole.
Payloads are signed with HMAC-SHA256 exactly like every other webhook event.