Pixellint

Pixellint

Pixellint is a spec-first validator for pixels, postbacks, conversion API payloads, and other measurement artifacts. It runs in a terminal, in CI, and in agents, and every finding carries a stable id, a severity, an evidence level, and the document it came from.

Broken pixels cost attribution, QA time, and campaign money. The tooling that exists is fragmented: vendor-specific helpers, enterprise tag auditors, and schema linters that know nothing about ad tech. Pixellint is the open validation layer underneath all of that.

$ pixellint validate url 'https://www.facebook.com/tr?ev=Purchse&em=buyer@example.com'
rulepack: core
  ok
rulepack: vendor/meta (vendor: meta)
  error   vendor.meta.param.id.missing   `id` is required on Meta Pixel requests but is not present. It is the numeric Pixel ID from Events Manager.
    fix: Set `id` to the numeric Pixel ID shown in Events Manager.
    docs: https://developers.facebook.com/docs/meta-pixel/get-started
  warning vendor.meta.param.ev.invalid   `ev` is `Purchse`, which is not one of the documented values: PageView, AddPaymentInfo, ...
    fix: Use a standard event name, or confirm the custom event is registered in Events Manager.
    docs: https://developers.facebook.com/docs/meta-pixel/reference
  error   vendor.meta.pii.unhashed_email A parameter carries what looks like a raw email address. Meta requires customer information to be normalized and SHA-256 hashed before it is sent.
    fix: Normalize the value, hash it with SHA-256, and send the hex digest instead of the plain address.
    docs: https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching

2 error(s), 1 warning(s), 0 info message(s) across 2 rulepack(s).

Server-side events are checked in the body, one event at a time:

$ pixellint validate json '{"data":[{"event_name":"Purchase","event_time":1770000000000,
    "action_source":"website","user_data":{"em":"buyer@example.com"}}]}'
rulepack: vendor/meta-conversions-api (vendor: meta)
  error   vendor.meta-conversions-api.body.event_time.invalid `event_time` must be at most 10 digits, but `1770000000000` has 13. Meta documents it as a Unix timestamp in seconds...
    fix: Send seconds, not milliseconds: divide a JavaScript `Date.now()` by 1000 and floor it.
  error   vendor.meta-conversions-api.body.purchase_requires_value_and_currency A `Purchase` event is missing `custom_data.value` or `custom_data.currency`.
  error   vendor.meta-conversions-api.body.website_requires_source_url The event is marked `action_source: website` but carries no `event_source_url`.

Install

cargo install pixellint          # CLI
cargo install pixellint-mcp      # MCP server
npm install pixellint            # library, WASM-backed

Or paste a URL into the playground at pixellint.org, which runs the same engine in your browser. Artifacts you test may be stored; see privacy. Vendor contracts are at pixellint.org/packs/. Guides for pixels, conversion APIs, and consent are at pixellint.org/docs/.

Start with the contracts people actually hit:

• Conversion API validator
• Pixel not firing
• Conversions API not working
• What is a conversion API
• Reddit CAPI
• DART Floodlight tags
• Facebook Pixel Helper vs Network
• Pinterest standard events

Use it

QA

Validate an inline artifact, a file with @path, or stdin with -:

pixellint validate url 'https://px.ads.linkedin.com/collect?pid=123456&fmt=gif'
pixellint validate postback @conversion-endpoint.txt --json
curl -s "$TAG_URL" | pixellint validate vast -

Callers that already extracted many URLs (Vastlint, an HTML adapter) pass them as a document. Identical values validate once:

pixellint validate-many @extracted.json --json

extracted.json is the wrapper in docs/MULTI_ARTIFACT_SCHEMA.md, or a JSON array of URL strings. Pixellint does not parse VAST, HTML, or GTM.

If the artifact is still a template with unexpanded macros, say so, and macro rules adjust:

pixellint validate url 'https://example.com/pixel?cb=[CACHEBUSTING]' --state template

CI

pixellint validate exits 0 when the artifact is clean or only produced warnings, 1 when any error-severity finding is present, and 2 on a usage or input problem.

- uses: aleksUIX/pixellint@v0.31.12
  with:
    path: fixtures/conversion-pixel.txt
    kind: url

version selects the CLI release (auto follows the action's own v* tag). Linux and macOS runners, x86_64 and aarch64. The Action downloads a prebuilt tarball from GitHub Releases.

Or install the CLI:

- name: Validate tracking artifacts
  run: |
    cargo install pixellint
    pixellint validate url @fixtures/conversion-pixel.txt

Agents

cargo install pixellint-mcp

pixellint-mcp speaks MCP over stdio and exposes three tools. It does not send artifacts; there is no hosted MCP on pixellint.org. Playground artifacts on pixellint.org may be stored; see pixellint.org/privacy.

• MCP Registry name: mcp-name: io.github.aleksUIX/pixellint

• list_rulepacks

• list_vendors, optionally filtered by category or attributing a single host

• validate_artifact, taking artifact_kind, artifact, and optional claimed_vendor, expansion_state, rulepacks, except_rulepacks

Responses include the structured findings, the detected vendors, and a severity summary, so an agent can act on the result without parsing prose.

Node and the browser

import { validate, isOk } from "pixellint";

const summary = validate("https://www.facebook.com/tr?ev=Purchase");
isOk(summary); // false, the pixel id is missing

Library

use pixellint_core::{ArtifactKind, Engine, ExpansionState, ValidationOptions, ValidationRequest};

let engine = Engine::default();
let request = ValidationRequest {
    artifact_kind: ArtifactKind::Url,
    artifact: "https://www.facebook.com/tr?id=1234567890123456&ev=PageView".to_string(),
    claimed_vendor: None,
    expansion_state: ExpansionState::Unknown,
};

let summary = engine.validate(&request, &ValidationOptions::default())?;
assert!(summary.is_ok());

Rulepacks

core runs on every URL-like artifact. Vendor packs run only when the artifact targets their endpoints, so you get vendor checks without asking for them, and nothing fires on an endpoint it does not understand. A conversion API body has no endpoint to go by, so those packs claim it by the shape of the payload.

Rulepack	Covers	Evidence
core	URL validity, transport, credentials, fragments, ad-tech macro handling, IAB consent signals	normative
vendor/meta	facebook.com/tr pixel requests	official vendor
vendor/meta-conversions-api	Graph API events edge, URL and JSON event payload	official vendor
vendor/google-analytics	GA4 Measurement Protocol, URL and JSON event payload	official vendor
vendor/google-analytics-collect	The /g/collect transport the Google tag uses in the browser	ecosystem reference
vendor/google-tag-manager	gtm.js, gtag/js, and ns.html loader requests	official vendor
vendor/google-ads-conversion	Google Ads conversion and view-through pixels	official vendor
vendor/google-ads-click-conversions	Google Ads UploadClickConversions JSON	official vendor
vendor/floodlight	Campaign Manager Floodlight activity tags	official vendor
vendor/cm360-tracking-ad	CM360 tracking ads, dc_trk_aid and dc_trk_cid	official vendor
vendor/cm360-vast-event	CM360 VAST event pixels, dc_oe on googlesyndication	ecosystem reference
vendor/google-ad-manager	Ad Manager /gampad/ads, iu sz output env gdfp_req correlator	official vendor
vendor/adobe-analytics	Adobe Analytics data collection beacons	official vendor
vendor/pinterest	Pinterest tag requests and the noscript fallback	official vendor
vendor/pinterest-conversions-api	Conversions API events, URL and JSON event payload	official vendor
vendor/snapchat	Snap Conversions API v3, URL and JSON event payload	official vendor
vendor/tiktok	TikTok Pixel loader events.js?sdkid=	ecosystem reference
vendor/tiktok-events-api	Events API pixel track and batch, URL and JSON event payload	official vendor
vendor/linkedin	LinkedIn conversion image pixels	ecosystem reference
vendor/linkedin-conversions-api	LinkedIn conversion events, single and batched	official vendor
vendor/microsoft-uet	Microsoft Advertising Universal Event Tracking	ecosystem reference
vendor/microsoft-conversions-api	Microsoft Advertising CAPI, URL and JSON event payload	official vendor
vendor/microsoft-clarity	Microsoft Clarity tag loader, project ID in the path	official template
vendor/reddit	Reddit Pixel conversion requests	ecosystem reference
vendor/reddit-conversions-api	Conversions API v3 events, URL and JSON event payload	official vendor
vendor/quora-conversions-api	Quora Conversion API JSON on /ads/v0/conversion	official vendor
vendor/nextdoor-conversions-api	Nextdoor Conversions API JSON on /v2/api/conversions/track	official vendor
vendor/x-conversions-api	X conversion API measurement events, URL and JSON payload	official vendor
vendor/x	X website tag image pixels on analytics.twitter.com, analytics.x.com, and t.co /adsct	ecosystem reference
vendor/the-trade-desk	The Trade Desk universal pixel iframe on insight.adsrvr.org/track/up	official vendor
vendor/criteo	Criteo OneTag loader ld.js?a=	official vendor
vendor/criteo-retail-media	Criteo Retail Media Delivery API on /delivery/retailmedia	official vendor
vendor/taboola	Taboola Pixel loader, account ID in the path	official vendor
vendor/hotjar	Hotjar tracking code, site ID in the path	official template
vendor/hubspot	HubSpot tracking code, Hub ID in the path	official template
vendor/awin	Awin fall-back conversion pixel and S2S read, including product-level bd[n]	official vendor
vendor/awin-basket	Awin product-level basket.php product_line rows	official vendor
vendor/partnerize	Partnerize conversion URL, campaign, clickref, and currency in the path	official vendor
vendor/amazon-ads	Amazon Ad Tag conversion loader, Tag ID in the path	ecosystem reference
vendor/amazon-vfw	Amazon DSP Firefly DV measurement, vstevt and dvparams on /dv/	ecosystem reference
vendor/doubleverify	DoubleVerify visit.jpg beacons, ctx cmp plc sid	ecosystem reference
vendor/doubleverify-event	DoubleVerify event.png quartiles, vstevt	ecosystem reference
vendor/freewheel	FreeWheel GET /ad/g/ ad requests, nw and csid or ssid	official vendor
vendor/outbrain	Outbrain conversion pixel on /pixel and /unifiedPixel	ecosystem reference
vendor/baidu	Baidu Tongji collect hm.gif?si=	ecosystem reference
vendor/kwai	Kwai Pixel loader, sdkid on s1.kwai.net	ecosystem reference
vendor/hubspot-pixel	HubSpot __ptq.gif collect pixel	ecosystem reference
vendor/cj	CJ Affiliate conversion pixel on emjcd.com/u	official vendor
vendor/impact	impact.com Universal Tracking Tag, UUID in the path	official template
vendor/rakuten	Rakuten Advertising conversion pixel on /ep	ecosystem reference
vendor/brevo-js	Brevo JavaScript tracker sa.js?key=	official template
vendor/yahoo-dot	Yahoo DSP Dot image pixels	official vendor
vendor/yandex-metrica	Yandex Metrica Measurement Protocol	official vendor
vendor/openai	OpenAI Ads image tag	official vendor
vendor/openai-conversions-api	OpenAI Ads Conversions API, URL and JSON payload	official vendor
vendor/kochava	Kochava S2S events, JSON payload	official vendor
vendor/singular	Singular S2S EVENT, query parameters	official vendor
vendor/amplitude	Amplitude HTTP V2 event uploads	official vendor
vendor/mixpanel	Mixpanel track ingestion	official vendor
vendor/posthog	PostHog capture, single and batched	official vendor
vendor/klaviyo	Klaviyo event creation	official vendor
vendor/braze	Braze user track: events, purchases, attributes	official vendor
vendor/brevo	Brevo Tracker REST trackEvent	official vendor
vendor/segment	Segment HTTP Tracking API, single and batched	official vendor
vendor/rudderstack	RudderStack HTTP Tracking API and Pixel API	official vendor
vendor/adjust	Adjust S2S events on s2s.adjust.com	official vendor
vendor/appsflyer	AppsFlyer S2S in-app events, URL and JSON payload	official vendor
vendor/appsflyer-onelink-impression	AppsFlyer OneLink impression URLs, template ID and pid	official vendor
vendor/branch	Branch Events API standard and custom events	official vendor
vendor/adform	Adform video and click tags on regional domains, banner number bn	official vendor
vendor/ispot	iSpot OTT impression pixel, TC-####-# in the path	official vendor
vendor/comscore	Comscore Direct collect c1, c2, c7	official vendor
vendor/quantcast	Quantcast Measure pixel, p-code a	official vendor
vendor/plausible	Plausible Events API JSON	official vendor
vendor/matomo	Matomo Cloud matomo.php, idsite and rec	official vendor
vendor/parsely	Parse.ly tracker loader, Site ID in the path	official vendor
vendor/crazyegg	Crazy Egg tracking script, account and script IDs in the path	official template
vendor/chartbeat	Chartbeat ping, site id h and account UID g	official vendor
vendor/heap	Heap.js 5 configuration loader, environment ID in the path	official vendor
vendor/mouseflow	Mouseflow project script, website ID in the path	official vendor
vendor/intercom	Intercom Messenger loader, workspace ID in the path	official vendor

Vendor directory

Rulepacks cover 133 endpoint families across 77 vendors. The vendor directory covers the rest by attribution: 120 vendor rows and 299 hosts, so an unrecognized pixel still gets a name. Full inventory: docs/STANDARDS.md.

$ pixellint validate url 'https://trc.taboola.com/actions?a=1'
rulepack: directory (vendor: taboola)
  info  directory.no_rulepack_coverage  This endpoint belongs to Taboola (native). No Pixellint rulepack covers it, so only the core checks ran. The `vendor/taboola` rulepack covers other Taboola endpoints, not this one.

Directory entries make one claim, that a host belongs to a vendor. They carry no parameter contracts, the finding is always info, and attribution never changes an exit code. See docs/VENDOR_DIRECTORY.md.

pixellint list-vendors
pixellint list-vendors --json

Select packs per run:

pixellint validate url "$ARTIFACT" --rulepack core
pixellint validate url "$ARTIFACT" --except vendor/meta
pixellint list-rulepacks --json

Full rule inventory with citations: docs/STANDARDS.md.

Evidence levels

Findings say where their authority comes from, and you can hold packs to different standards accordingly:

• normative: a formal standard such as the WHATWG URL Standard or an RFC
• official_vendor: a parameter contract the vendor publishes, with the URL
• official_template: vendor-published templates or SDK behavior
• ecosystem_reference: consistent real-world behavior the vendor generates in its own UI but does not document
• heuristic: Pixellint's judgment, labeled as such

The manifest loader refuses to compile a pack that claims official_vendor without citing documentation.

Custom rulepacks

Rulepacks are data, not code. First-party vendor packs are written in the same JSON format you can write for an internal endpoint:

{
  "id": "custom/acme",
  "display_name": "Acme internal pixel",
  "description": "Contract for the internal conversion endpoint.",
  "vendor": "acme",
  "source_level": "heuristic",
  "match": { "hosts": ["px.acme.example"], "path_prefixes": ["/collect"] },
  "params": [
    { "name": "aid", "requirement": "required", "format": { "kind": "integer" } },
    { "name": "ev", "requirement": "required", "format": { "kind": "enum", "values": ["view", "purchase"] } }
  ]
}

pixellint validate url 'https://px.acme.example/collect?ev=purchase' --rulepack-file acme.json

The format is documented in docs/RULEPACK_SCHEMA.md.

Private pixels that only need a name, not a parameter contract, belong in a directory overlay:

pixellint validate url 'https://px.acme.example/collect' --directory-file extra.json

The overlay uses the same entry shape as the built-in directory. New hosts only; it cannot steal a first-party host. Contribute an upstream host through a PR: CONTRIBUTING.md.

What Pixellint does not do

• It does not extract artifacts from documents. html, js, and gtm are not validation kinds; the CLI exits 2 if you pass them. Callers such as Vastlint parse VAST, HTML, or GTM containers and hand Pixellint the URLs they found. pixellint validate-many wraps those extracted URLs. The document result model is in docs/MULTI_ARTIFACT_SCHEMA.md.
• It does not fire requests or check whether an endpoint responds.
• It does not auto-fix. Findings carry fix hints; applying them is on you.

Evidence

Every rule is backed by tests: unit tests in crates/pixellint-core/src/, a golden corpus in fixtures/ with one directory per rulepack, and integration tests that drive the real CLI binary and the real MCP stdio transport.

cargo test --workspace

Benchmark

In-process engine speed over the golden corpus, D1-shaped synthetic pixels, and large validate-many batches:

cargo run -p pixellint-bench --release -- --quick
cargo run -p pixellint-bench --release
cargo run -p pixellint-bench --release -- --mode load --heavy

See bench/README.md.

Docs

• Standards and rule inventory
• Vendor directory
• npm package
• Rulepack manifest schema
• Architecture
• Roadmap
• Multi-artifact output model

License

Apache-2.0. Pixellint is not affiliated with or endorsed by any vendor named in its rulepacks; see NOTICE.