Skip to main content
Use one Wildcard partner account for all the sites your platform creates. Register each site as a tracked domain, organize related sites into a domain group, and request visitors for that group. You do not need a new Wildcard account or login for every site.

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

Use GET /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.
Each data row has a domain and normalized path, with:
  • human.pageViews: human-classified page loads, including unidentified visitors.
  • human.uniqueVisitors and human.sessions: distinct recorded visitor and session IDs. Missing IDs are disclosed in pageViewsWithoutVisitorId and pageViewsWithoutSessionId; they are never invented from IP addresses.
  • ai.requests and ai.byAgent: server-observed AI page requests, with stable agent IDs such as openai-crawler, openai-crawler-user, anthropic-crawler, and perplexity-crawler. ai.pageViews is 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, identifiedPeople contains matched person IDs, names and company names. human.identifiedPageViews and human.unidentifiedPageViews partition 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 to POST /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.
For request-time hooks such as Next.js Proxy, send 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:
If your site already runs a Next.js proxy (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:
Import the helper from the downloaded module. Run this only for explicitly opted-in sites with a configured secret; keep it independent of any other telemetry provider’s enable switch. Preserve the existing route matcher and response. Use the actual configured site hostname, never an unvalidated Host header to construct the allowed-host list. This adapter skips prefetches, RSC-only requests and API routes. It cannot see a final response status. Set the key as a deployment secret and explicitly enable opted-in sites. The collector strips query strings/fragments, skips non-HTML responses and prefetches, and retries transient failures once with the same event identity. This small adapter is best effort: monitor errors. For durable delivery or high volume, enqueue observations and submit batches; honor 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 named Acme. 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.
The response is { "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:
The response includes 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, with domain_group_id in the query string:
The filter matches the exact tracked hostnames in the group, normalizing 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.
To fetch only that group’s journey events, use the same filter on /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?”, add visited_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_until is exclusive; a window is at most 31 days.
  • limit goes up to 250 in this mode. Follow pagination.nextCursor until it is absent; a page can hold fewer than limit people 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-groups returns { "groups": [...] } for your account.
  • PATCH /v1/partner/domain-groups accepts groupId plus name and/or domains. The domains array replaces membership and may contain only sites already tracked by your partner account. An empty array empties the group.
  • DELETE /v1/partner/domain-groups accepts { "groupId": "acme" }. It removes the group without deleting sites or visitor history.
Paused sites remain valid members for historical visitor queries. Removed sites are omitted from group membership. Changing a group never enables tracking. Removing and then re-adding a site does not restore its old group membership; explicitly assign it again.

Attribution on every record

People and events both carry the client they belong to:
Filter to one client with either 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/people returns only that client’s visitors.
  • /v1/people/{id}/events returns 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.
Each scoped key gets its own hourly rate limit, so one client’s traffic never consumes another’s. Rotating and revoking. Selecting Rotate key issues a new key and stops the old one working immediately. Revoke key removes API access while leaving tracking untouched.

Reading a journey

A journey is the ordered stream of everything a visitor did:
Two things to build for: Journeys vary enormously. One visitor has three events; another has several thousand. Always page with 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 the person.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.
Events arrive oldest-first, so a journey reads forwards. If a visitor is active enough to exceed the per-delivery cap, 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.