# Velotrak VeloTrak (ad tracking software, velotrak.app) is a self-hosted ad tracker. Self-hosted ad tracker: clicks and conversions stay in your own PostgreSQL + ClickHouse. Flat price, never per click. CAPI on every plan, 90 MCP tools for AI agents. One Go binary on Linux, PostgreSQL for the ledger, ClickHouse for clicks. Install: curl -fsSL https://velotrak.app/install.sh | sudo bash. Clicks are not metered. Pro is charged $49 every month or $490 every year (the site shows the annual plan as $41/mo). Team is charged $99 every month or $990 every year (shown as $83/mo). Free is $0. Founder is $399 once. CAPI for Meta, TikTok and Google is on every plan, including Free. MCP is 90 tools; edits and deletes show a diff and wait for confirmation. Data stays in the customer's databases. Telemetry is off by default. Full export anytime. Pricing page: https://velotrak.app/pricing/ Chinese pricing page: https://velotrak.app/zh/pricing/ Alternatives index: https://velotrak.app/alternatives/ Docs: https://velotrak.app/docs/ Chinese docs: https://velotrak.app/zh/docs/ Blog: https://velotrak.app/blog/ RSS: https://velotrak.app/blog/rss.xml Short brief: https://velotrak.app/llms.txt GitHub: https://github.com/VeloTrak/Velotrak Releases: https://github.com/VeloTrak/Velotrak/releases ## Voluum alternative Velotrak is a self-hosted alternative to Voluum. Clicks and conversions stay in PostgreSQL and ClickHouse on your server, and the license is a flat price (Pro is $49/month or $490/year), not an event quota. Voluum is a hosted tracker. On 14 Nov 2026 its public price table listed Profit at $149/month or $119/month billed yearly for up to 1,000,000 events, and the page was also running a Black Month promotion. - Pricing model Velotrak: Flat license. Free is $0. Pro is $49/month or $490/year (shown as $41/mo). Team is $99/month or $990/year (shown as $83/mo). Founder is $399 once. Clicks are not a line item. Voluum: Hosted subscription with an included event quota, then overage. Source: Voluum pricing page, checked 2026-11-14. List prices: Profit $149/mo or $119/mo yearly; Scale $349 or $299; Start-up $599 or $539; Agency $999 or $799; Enterprise $1,999 or $1,599. A Black Month promotion was on the page, so the card you see can be lower than that list. - Hosting Velotrak: You run it on your own Linux server. The license does not include a VPS. The site says a VPS from about $10/month runs the 2 vCPU / 4 GB floor. Voluum: Sold as a hosted subscription on voluum.com. The pricing page does not offer a self-hosted license. - Data ownership Velotrak: Clicks in your ClickHouse, ledger in your PostgreSQL. Full export anytime. Telemetry is off by default. Voluum: Tracking runs on Voluum's service. - CAPI Velotrak: Meta, TikTok and Google on every plan, including Free. One account per platform on Free; unlimited CAPI accounts on Pro and Team. Voluum: The pricing page lists Conversion API postback for major traffic platforms: Facebook Ads, Google Ads, TikTok, Bing and Yahoo. On 14 Nov 2026 it was not included on Profit, Scale or Start-up, an add-on on Agency, and included on Enterprise. - Per-event limits Velotrak: No click quota on any plan. Free stops at 3 active campaigns and reports on the last 15 days. Pro and Team remove those limits. Voluum: Pricing cards count visits, clicks, conversions and impressions. On Start-up and above, 10 impressions count as 1 event. Caps: Profit up to 1,000,000; Scale up to 5,000,000; Start-up up to 10,000,000; Agency 25,000,000; Enterprise 60,000,000. Past the quota, tracking continues and overage is billed. The page's Profit example is $0.06 per 1,000 events past 1,000,000. Voluum's tracking docs say paid events are visits, clicks and conversions and that impressions are free. That wording does not match the pricing page, so read both. When the other product is the better fit: - You want Voluum to host the tracker, and you do not want to run Linux, Docker, PostgreSQL and ClickHouse. - You want the hosted extras on their cards, such as the anti-fraud kit, workspaces and an onboarding call. - A small event quota matches your volume and you would rather pay their subscription than rent a VPS. Profit's yearly list price is $119/month for up to 1,000,000 events. Velotrak Pro is $49/month or $41/month billed annually, plus the VPS. Voluum's pricing cards also list MCP with a daily request cap: 20 on Profit, 60 on Scale, 100 on Start-up, 200 on Agency and 1,000 on Enterprise, with a note that scope can be increased as an add-on. Velotrak's MCP is 90 tools, read-only on Free, and edits or deletes show a diff before anything is applied. There is no daily request cap on the Velotrak plans. Source: Voluum pricing page, checked 2026-11-14. FAQ: - Q: Is Velotrak a Voluum alternative? A: Yes, if you want the tracker on your own server. Velotrak stores clicks and conversions in your PostgreSQL and ClickHouse and charges a flat license. Voluum is hosted and bills an event quota plus overage. - Q: Does Voluum include CAPI on every plan? A: No. On 14 Nov 2026 the pricing page listed Conversion API postback for Facebook Ads, Google Ads, TikTok, Bing and Yahoo as not included on Profit, Scale or Start-up, an add-on on Agency, and included on Enterprise. Velotrak includes Meta, TikTok and Google CAPI on every plan, including Free. - Q: What does Voluum list for 10 million events? A: The Start-up card says up to 10,000,000 events. Source: Voluum pricing page, checked 2026-11-14. The list price was $599/month or $539/month billed yearly. A Black Month promotion was running, so the card can differ. Velotrak Pro stays $49/month or $490/year at that volume, plus your VPS. Sources (last checked 2026-11-14): - Voluum pricing: https://voluum.com/pricing/ - Voluum docs, what an event is: https://doc.voluum.com/article/tracking Page: https://velotrak.app/alternatives/voluum/ ## RedTrack alternative Velotrak is a self-hosted alternative to RedTrack. You keep clicks in your own ClickHouse and pay a flat license (Pro $49/month or $490/year), not a monthly event allowance. RedTrack is a hosted tracker. On 14 Nov 2026 its affiliate pricing page showed Solo at $169/month or $118/month on the annual price for 5 million events, and the page labeled that annual price a Black Friday discount that renews at the same rate. - Pricing model Velotrak: Flat license. Free is $0. Pro is $49/month or $490/year (shown as $41/mo). Team is $99/month or $990/year (shown as $83/mo). Founder is $399 once. RedTrack: Hosted plans sized by events and seats. Affiliate cards on 14 Nov 2026: Solo $169/mo or $118/mo annual ($1,420/yr) for 5 million events and 1 user; Team $399 or $279 ($3,352/yr) for 20 million events and 5 users; Enterprise $999 or $699 ($8,392/yr) for 75 million events and 15 users. The page said Black Friday was 30% off the 12-month price and that the renewal keeps that price. - Hosting Velotrak: Self-hosted on your Linux server. The license does not include the VPS. RedTrack: Hosted subscription. The pricing page is a cloud product with event allowances, not a license you install. - Data ownership Velotrak: Your PostgreSQL and ClickHouse. Full export anytime. Telemetry off by default. RedTrack: Tracking runs on RedTrack's service. - CAPI Velotrak: Meta, TikTok and Google on every plan, including Free. RedTrack: The pricing page says Conversion API is on the affiliate plans, and names native CAPI for Meta, Google, TikTok, Snapchat, Microsoft/Bing, X, Pinterest and OpenAI Ads. Networks without native CAPI can be forwarded with S2S postbacks or JSON. - Per-event limits Velotrak: Clicks are not metered. Plan limits are campaigns, report history, seats and installs, not a click quota. RedTrack: The page defines tracked events as clicks, conversions and postbacks per month. Solo includes 5 million, Team 20 million, Enterprise 75 million. There is no 10 million tier. Overage is charged per 1,000 events and the page says tracking does not switch off. When the other product is the better fit: - You want RedTrack to host the tracker and you do not want to run a Linux server. - You need the wider native CAPI list on their pricing page (Snapchat, Microsoft/Bing, X, Pinterest, OpenAI Ads) in addition to Meta, TikTok and Google. - You want the ecommerce plans on the same page (Relay, Brand, Agency). Those are a separate price list from the affiliate cards above. The same pricing page lists MCP and API access on Solo, and a fixed add-on named "MCP / API access — Premium, 1,000 requests per minute" at $199/month or $139/month on the annual price ($1,672/year). AI Copilot is named in an every-plan feature line on that page. That $139 figure is the premium MCP/API add-on, not a separate Copilot price. The same URL also has an ecommerce list priced by tracked revenue. At the $250K tier on 14 Nov 2026: Relay $0, Brand $99/month or $69/month billed yearly ($832/year), Agency $599/month or $419/month billed yearly ($5,032/year). FAQ: - Q: Is Velotrak a RedTrack alternative? A: Yes, if you want self-hosting and a flat license. RedTrack is hosted and includes an event allowance, then overage. Velotrak does not meter clicks. Pro is $49/month or $490/year, plus a server you rent. - Q: Does RedTrack charge $399/month for 10 million events on annual billing? A: Not on the page checked 14 Nov 2026. Team's monthly price is $399 and its annual price is $279/month, and Team includes 20 million events, not 10 million. Solo includes 5 million. There is no 10 million card. - Q: Is RedTrack CAPI only on expensive plans? A: Their pricing page says Conversion API is included on the affiliate plans, starting at Solo, and lists Meta, Google, TikTok and several other platforms. Velotrak includes Meta, TikTok and Google CAPI on Free as well. Sources (last checked 2026-11-14): - RedTrack pricing: https://www.redtrack.io/pricing/ Page: https://velotrak.app/alternatives/redtrack/ ## Binom alternative Velotrak and Binom can both run on your server, and neither bills per click. Velotrak is one Go binary with PostgreSQL and ClickHouse, and Meta, TikTok and Google CAPI are on every plan including Free. On 14 Nov 2026 Binom's price page showed v2 at $149 on the monthly toggle and $104 on the yearly toggle, and its changelog says Facebook CAPI is in beta as of 6 Oct 2026. - Pricing model Velotrak: Flat license. Free is $0. Pro is $49/month or $490/year (shown as $41/mo). Team is $99/month or $990/year (shown as $83/mo). Founder is $399 once. The VPS is extra. Binom: The v2 card shows $149 and $104 under the monthly and yearly toggles, and an additional license at $75 and $52 in the same pattern. The headline is one price for any click volume. Binom Cloud is listed at $299. - Hosting Velotrak: Self-hosted on Linux. Installer is one command and brings PostgreSQL and ClickHouse. Binom: Self-hosted, and a cloud plan. Their FAQ says cloud plans came later and include the server, monitoring and optimization. The v2 card is the self-hosted license. - Data ownership Velotrak: Your PostgreSQL and ClickHouse. Full export. Telemetry off by default. Binom: Self-hosted v2 stores data on the server you run. Binom Cloud is their hosted option at $299. - CAPI Velotrak: Meta, TikTok and Google on every plan, including Free. Binom: Changelog 2.36.00 (6 Oct 2026) adds Facebook CAPI Beta. The price page does not describe a Conversions API. TikTok and Google CAPI are not in that changelog entry. - Per-event limits Velotrak: No click quota. Free is limited by campaigns (3 active) and report window (15 days), not by clicks. Binom: The price page says one price for any click volume, and the FAQ says a large number of clicks is still only the license fee. The same v2 card also says traffic up to 260 million a day. Cloud says traffic up to 2 million a day. When the other product is the better fit: - You want Binom's cloud plan at $299 so they run the server. - You already run Binom and its PHP stack, and Facebook CAPI beta covers the platform you need. - You want the v2 card's unlimited users and domains on one license. Velotrak Team is the plan that adds unlimited users, roles and an audit log; Pro is capped at 3 users. Binom's price page does not mention an MCP server. Absence on that page is not proof the feature is missing; check their current docs if you need it. Velotrak documents 90 MCP tools, with a diff you confirm before edits or deletes. The v2 card also lists a 30-day trial, unlimited users and unlimited domains. Their FAQ says you can cancel a subscription. FAQ: - Q: Is Velotrak a Binom alternative? A: Yes. Both can be self-hosted and both use a flat license instead of per-click billing. Velotrak is a Go binary with PostgreSQL and ClickHouse. Binom v2's changelog says it runs on PHP 8.4. - Q: Does Binom have CAPI? A: Changelog 2.36.00 on 6 Oct 2026 says you can send conversions to Facebook through the Conversions API, marked beta. The price page does not mention TikTok or Google CAPI. Velotrak includes all three on every plan, including Free. - Q: Is Binom still on PHP 7.4? A: No. Changelog 2.28.00 (2 Dec 2025) says the tracker runs on PHP 8.4. Older install notes that mention PHP 7.4 are out of date. Sources (last checked 2026-11-14): - Binom price: https://binom.org/price - Binom changelog: https://binom.org/changelog Page: https://velotrak.app/alternatives/binom/ ## Keitaro alternative Velotrak is a self-hosted alternative to Keitaro with a published USD license and Meta, TikTok and Google CAPI on every plan, including Free. Keitaro is a self-installed license with no per-event fee. On 14 Nov 2026, billed yearly: Starter €40/month, Advanced €72/month, Expert €104/month, Team €200/month and Enterprise €400/month. Facebook Conversions API starts at Advanced in their docs; Google Ads and TikTok conversions start at Expert. - Pricing model Velotrak: Flat USD license. Free $0. Pro $49/month or $490/year (shown as $41/mo). Team $99/month or $990/year (shown as $83/mo). Founder $399 once. Keitaro: Self-installed license, no per-event fee. Yearly prices on 14 Nov 2026: Starter €40/month (1 user, 1 domain), Advanced €72/month (1 user, 100 domains), Expert €104/month (up to 5 users, 500 domains). Business plans billed yearly: Team €200/month (50 users) and Enterprise €400/month (unlimited users). The official pricing API lists monthly prices of €49, €89, €129, €249 and €499, with 20% off for a year and 10% off for six months. Those discounts line up with the yearly prices on the page. - Hosting Velotrak: Self-hosted on your Linux server. You rent the VPS. Keitaro: A license you install on your own server. The docs start with an installation guide. The price list has no per-event fee. - Data ownership Velotrak: Your PostgreSQL and ClickHouse. Full export. Telemetry off by default. Keitaro: The install path puts the tracker on a server you run. - CAPI Velotrak: Meta, TikTok and Google on every plan, including Free. Keitaro: Their Facebook Conversions doc says the integration sends conversions via the Conversions API and is marked Advanced, Expert, Team and Enterprise. Google Ads and TikTok docs say those integrations send conversions and are marked Expert, Team and Enterprise. Starter is not in those headings. - Per-event limits Velotrak: No click quota on any plan. Keitaro: No per-event fee. The public price list is organized by users, domains and integrations. The official pricing API does not include an event quota. When the other product is the better fit: - You want Keitaro's edition model, landing-page editor and the routing stack their docs describe, and you are fine buying the license in euros. - You only need Facebook Conversions API and an Advanced license is enough. Google and TikTok conversions are documented from Expert upward. - You want their official MCP and you are on Expert, Team or Enterprise. Their docs say MCP starts there, from version 11.5.0. Keitaro's MCP doc also says tracker settings, users, permissions, bot lists and triggers are not MCP tools, and that landing pages come back as a read-only list. Velotrak's MCP can create and edit landers; edits and deletes still wait for you to confirm the diff. FAQ: - Q: Is Velotrak a Keitaro alternative? A: Yes. Both are self-hosted. Velotrak publishes USD prices and includes Meta, TikTok and Google CAPI on Free. Keitaro publishes euro license prices, and its conversion integrations are gated by edition. - Q: Does Keitaro publish prices? A: Yes. On 14 Nov 2026, billed yearly: Starter €40/month (1 user, 1 domain), Advanced €72/month (1 user, 100 domains), Expert €104/month (up to 5 users, 500 domains), Team €200/month (50 users) and Enterprise €400/month (unlimited users). The official pricing API lists the monthly prices as €49, €89, €129, €249 and €499, with 20% off for a year and 10% off for six months. - Q: Does Keitaro have MCP? A: Their MCP doc says it is available on Expert, Team and Enterprise from Keitaro 11.5.0 (stable) or 11.5-beta. Default use is questions and logs. Edit mode can change campaigns, streams and offers, and the doc tells you to check the change before confirming. Velotrak's 90 tools are on every plan, read-only on Free, with the same diff-then-confirm step for edits and deletes. Sources (last checked 2026-11-14): - Keitaro pricing: https://keitaro.io/en/pricing - Keitaro individual pricing: https://keitaro.io/pricing-individual - Keitaro business pricing: https://keitaro.io/pricing-business - Keitaro Facebook Conversions: https://docs.keitaro.io/en/third-party-integrations/facebook-conversions.html - Keitaro MCP: https://docs.keitaro.io/en/settings/mcp.html Page: https://velotrak.app/alternatives/keitaro/ ## BeMob alternative Velotrak is a self-hosted alternative to BeMob. Clicks stay in your ClickHouse and the license does not grow with events (Pro is $49/month or $490/year). BeMob is a hosted tracker. On 14 Nov 2026 its pricing page listed a free plan at 100,000 events and Professional at $49/month for 1,000,000 events. An event, in their footnote, is every impression, visit, click or conversion. - Pricing model Velotrak: Flat license. Free $0 with unmetered clicks and 3 active campaigns. Pro $49/month or $490/year (shown as $41/mo). Team $99/month or $990/year (shown as $83/mo). Founder $399 once. BeMob: Hosted plans with an event quota. On 14 Nov 2026: Free $0 for 100,000 events and 1 month of retention, overage cannot be purchased. Professional $49/month for 1,000,000 events, overage $0.05 per 1,000. Business $249/month for 10,000,000 events and 3 months of retention, overage $0.025 per 1,000. Enterprise $499/month for 30,000,000 events and 6 months of retention, overage $0.02 per 1,000. - Hosting Velotrak: Self-hosted on your Linux server. You rent the VPS. BeMob: Hosted. Their FAQ says you do not need a server and that BeMob is a fully cloud tracker. - Data ownership Velotrak: Your PostgreSQL and ClickHouse. Full export anytime. Telemetry off by default. BeMob: Tracking runs on BeMob's service. Retention on the pricing cards is 1 month on Free and Professional, 3 months on Business and 6 months on Enterprise. - CAPI Velotrak: Meta, TikTok and Google on every plan, including Free. BeMob: The Facebook integration doc says conversions are sent via the Conversions API, sold as an add-on at $19/month on any plan. No TikTok or Google CAPI page was found in the official docs on 14 Nov 2026. - Per-event limits Velotrak: No click quota. Free limits are 3 active campaigns and a 15-day report window. BeMob: Their footnote defines an event as every impression, visit, click or conversion. Free cannot buy overage. Paid plans can. The public feature table lists 0 tracking domains on Free and Professional, 3 on Business and 5 on Enterprise. When the other product is the better fit: - You want a free hosted plan to test with, capped at 100,000 events, and you do not want to run a server. - Your traffic is small enough that Professional at $49/month for 1,000,000 of their events is simpler than renting a VPS. Remember their event counts impressions and visits, not only clicks. - You want BeMob to host the tracker and to handle the server. Velotrak does not sell hosting. BeMob's public feature table on that pricing page also caps campaigns, offers, landing pages and users by plan. Those caps are separate from the event quota. Velotrak Free caps active campaigns at 3; Pro removes the campaign cap. FAQ: - Q: Is Velotrak a BeMob alternative? A: Yes, if you want the data on your own server and a license that does not meter clicks. BeMob is cloud-hosted and bills by events. Velotrak Free also costs $0, with a limit of 3 active campaigns rather than 100,000 events. - Q: What does BeMob count as an event? A: The pricing footnote says an event is every impression, visit, click or conversion. A funnel with an impression, a visit and a lander click spends three events before a conversion. - Q: Does BeMob include CAPI? A: Facebook only, as an add-on. The official Facebook settings doc says the integration sends conversions via the Conversions API and costs $19/month on any plan. No TikTok or Google CAPI page was found in the official docs on 14 Nov 2026. Velotrak includes Meta, TikTok and Google CAPI on every plan, including Free. Sources (last checked 2026-11-14): - BeMob pricing: https://bemob.com/en/pricing - BeMob pricing structure: https://docs.bemob.com/en/pricing-structure - BeMob Facebook integration: https://docs.bemob.com/en/facebook-settings Page: https://velotrak.app/alternatives/bemob/ ## Docs ### Getting started with Velotrak Velotrak is a self-hosted ad tracker: one Go program on Linux, PostgreSQL for the ledger, and ClickHouse for clicks. Install with one command, create the admin in the wizard, then send traffic to a /click/ link. ## What Velotrak is Velotrak (ad tracking software at velotrak.app) records ad clicks and conversions on a server you run. It is not the Timex Velo-Trak watch. The process serves the click redirect, the admin UI, the MCP endpoint, and background jobs. PostgreSQL holds configuration and the conversion ledger. ClickHouse holds the click log used by reports. Clicks are not metered on any plan. A license limits admin actions such as how many campaigns can be active. It does not sit on the click, postback, or CAPI delivery path. Prices and plan caps are on the [licensing](/docs/licensing/) page and match the [pricing](/pricing/) page. ## What you need The installer runs on Linux with systemd, as root, with curl. It accepts x86_64 and arm64. On a fresh install it warns when RAM is under 3500 MB. The warning names 2 vCPU / 4 GB as the minimum. The script does not count CPUs. The site recommends 4 vCPU / 8 GB. The license does not include the server. You can look at the admin before installing. The [live demo](https://demo.velotrak.app) opens with the shared account filled in. You can build campaigns there, and the site says the data resets daily. ## First session Run the installer, open the setup link it prints, and create the first admin. The wizard then checks the environment, asks for timezone and currency, and offers a license step you can skip. Currency choices in that step are USD, CNY, EUR, GBP, and JPY. The password must be at least 8 characters and at most 72 bytes. After that, the usual chain is a traffic source, an affiliate network and offer, a flow, and a campaign on a domain. The campaign link looks like `https://your-domain/click/`. The next pages cover [installation](/docs/installation/) and [those objects](/docs/concepts/). Page: https://velotrak.app/docs/getting-started/ ### Install Velotrak on Linux On a Linux server, as root, run curl -fsSL https://velotrak.app/install.sh | sudo bash. The script installs Docker if needed, starts PostgreSQL and ClickHouse on localhost, and runs Velotrak as a systemd service. ## Run the installer The public script is [velotrak.app/install.sh](https://velotrak.app/install.sh). Release binaries are on [GitHub](https://github.com/VeloTrak/Velotrak/releases). ```bash curl -fsSL https://velotrak.app/install.sh | sudo bash ``` The script refuses to run when you are not root, when the OS is not Linux, or when systemd or curl is missing. It accepts x86_64 (amd64) and aarch64 (arm64). On a fresh install, RAM under 3500 MB produces a warning that names 2 vCPU / 4 GB as the minimum. That warning does not stop the script, and the script does not check the CPU count. The site recommends 4 vCPU / 8 GB. A fresh install does three things: 1. If Docker is missing, it installs Docker from get.docker.com, then starts PostgreSQL and ClickHouse with Docker Compose under `/opt/velotrak/stack`. Postgres listens on `127.0.0.1:15432`. ClickHouse listens on `127.0.0.1:19000`. Passwords are generated into that directory's `.env`. 2. It downloads the release binary for this machine from the public `velotrak/velotrak` repository and checks SHA-256 against `checksums.txt`. 3. It writes `/opt/velotrak/velotrak.env`, installs a `velotrak` systemd service that runs `/opt/velotrak/velotrak` as user `velotrak`, and waits until `http://127.0.0.1:8080/healthz` returns. The default HTTP port is 8080. Data goes to `/var/lib/velotrak`. The binary also tries to download a DB-IP city lite database into `/var/lib/velotrak/geoip`. If that download fails, the script warns that country, region, and city stay empty until a database is placed there. ## Choose a version or your own databases Pin a release tag that exists on the releases page: ```bash curl -fsSL https://velotrak.app/install.sh | sudo VELOTRAK_VERSION=v1.2.3 bash ``` Replace `v1.2.3` with a real tag. To skip Docker and use databases you already run: ```bash curl -fsSL https://velotrak.app/install.sh | sudo VELOTRAK_EXTERNAL_DB=1 bash ``` The script then tells you to set `VELOTRAK_PG_DSN` and `VELOTRAK_CH_DSN` in `/opt/velotrak/velotrak.env` and start the service with `systemctl start velotrak`. Migrations are compiled into the binary. `velotrak migrate` applies them without starting the server. To install a binary you already have: `sudo ./install.sh ./velotrak`. ## Open the setup wizard Until the first admin exists, the process writes a one-time token to `/var/lib/velotrak/setup.token` (mode 0600) and the installer prints a URL of the form `http://:8080/admin/#setup=`. `POST /api/setup` without that token returns 403. You can set `VELOTRAK_SETUP_TOKEN` yourself (at least 16 characters) before the first start. The file is removed after the admin account is created. The wizard is welcome, environment check, admin account, general settings, license (skippable), then done. The environment check reports the app, PostgreSQL, ClickHouse, GeoIP, resources, and ports. General settings save a timezone and a currency of USD, CNY, EUR, GBP, or JPY. The password is 8 characters to 72 bytes. Activating a license can wait; see [plans](/docs/licensing/). The admin path defaults to `/admin/`. Set `VELOTRAK_ADMIN_HOST` to one or more hostnames when the admin should not answer on the tracking domain. The operator notes say that an operator who can upload landers, or a third-party lander, should not share an origin with the admin. ## Domains and TLS Register every hostname you send traffic to on the Domains page. `VELOTRAK_TLS_DOMAIN` is treated as a tracking domain and turns on the built-in ACME client, which binds 443 and issues certificates for that name and for domains you add in the admin. Point DNS at the server, then use Check on the domain. Check is an external probe. For a certificate you already have, set `VELOTRAK_TLS_CERT_FILE` and `VELOTRAK_TLS_KEY_FILE`. The generated env file includes commented examples. If a CDN other than Cloudflare sits in front, put its ranges in `VELOTRAK_TRUSTED_PROXIES` so the click's IP is the visitor, not the proxy. Cloudflare's own ranges are already compiled in. Orange-cloud TLS, caching, and the paths that must stay untouched are in [Cloudflare](/docs/cloudflare/). Unregistered hosts do not get a normal lander origin: the server sandboxes those responses, and a pixel on that host cannot use the tracking cookies. ## Upgrade Run the same command again. The previous binary is kept as `/opt/velotrak/velotrak.old`. The env file, generated passwords, and data directory are left in place. If the service does not answer, `journalctl -u velotrak -n 50 --no-pager` is what the installer tells you to read. ## Stop or remove it The repository does not ship an uninstall script. `systemctl disable --now velotrak` stops the service the unit file installed at `/etc/systemd/system/velotrak.service`. The installer created `/opt/velotrak` (binary, env, and the Compose stack) and `/var/lib/velotrak` (data, `master.key`, certificates, backups). Deleting those directories deletes the local databases' Docker files and the tracker data, including backups. Copy `master.key` first if you still need to decrypt stored integration credentials. See [backup](/docs/backup/). Plan limits after install are on the [pricing](/pricing/) page. Page: https://velotrak.app/docs/installation/ ### Cloudflare in front of Velotrak When Cloudflare connects straight to Velotrak, the click stores the visitor from CF-Connecting-IP, not the edge address. Use SSL mode Full (strict) with a certificate file. The built-in ACME client cannot issue or renew while that proxy terminates TLS. ## Visitor IP Clicks, GeoIP, the bot check, flow rules on the `ip` field, the LP Protect entry token, admin login limits, and the audit log all use one client-IP function. The TCP peer is the client whenever that peer is not a trusted proxy. Forwarding headers on a direct public connection are ignored, so a visitor cannot pick their own address by sending them. A trusted proxy is a Cloudflare edge address from the list compiled into the binary, a loopback or private address, or a CIDR you set in `VELOTRAK_TRUSTED_PROXIES`. From a trusted peer, `X-Forwarded-For` is read from the right, across every header line. Trusted hops are skipped. The first hop that is not a trusted proxy is the visitor. The left end is whatever the client wrote, so it is never taken by itself. `CF-Connecting-IP` is used when the peer, or one of those hops, is a Cloudflare address. It is also used when the peer is loopback and the request has no `X-Forwarded-For` at all. That is a cloudflared tunnel on this machine; the public demo is published that way. `True-Client-IP` and `X-Real-IP` are not read. Standard orange cloud sends `CF-Connecting-IP`, which is the header that counts. Orange cloud straight to the Velotrak process is the direct Cloudflare case. Leave `VELOTRAK_TRUSTED_PROXIES` empty for Cloudflare. That variable is for a different CDN in front of the server. The Cloudflare list is fixed in the binary. It is not downloaded on startup. On 17 November 2026 it matched the published lists at [cloudflare.com/ips-v4](https://www.cloudflare.com/ips-v4) and [cloudflare.com/ips-v6](https://www.cloudflare.com/ips-v6). An edge address that a later Cloudflare change adds, and that this binary does not contain, is an ordinary public client: the headers are ignored and the stored IP is that edge. A proxy you run between Cloudflare and Velotrak has to append `X-Forwarded-For`. For nginx that is `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`. The walk then meets the Cloudflare hop and uses `CF-Connecting-IP`. A proxy on `127.0.0.1` that sends only `CF-Connecting-IP` is accepted. A Docker bridge or LAN address that forwards headers without appending `X-Forwarded-For` is stored as itself, and a `CF-Connecting-IP` the visitor supplied is ignored. The installer runs Velotrak on the host, with no extra proxy, so orange cloud to that host is the direct case. The same address is what the rest of the tracker uses: - GeoIP looks up country, region, city, and ISP. An empty country after install is a missing database at `/var/lib/velotrak/geoip/dbip-city.mmdb`. A proxy address comes back as that proxy's location, which is a filled-in country, not an empty one. - The bot check matches user-agent patterns and a built-in datacenter list (ranges such as AWS, GCP, and Azure). Cloudflare's ranges are not on that list, so an edge address is not marked `dc_ip` on its own. A custom IP rule you saved matches whatever address was stored. - A flow rule on `ip` compares that address. - LP Protect signs the `vt_lp` entry token, valid for 5 minutes, with that IP and the user agent. The session cookie after a valid entry lasts 2 hours and is not tied to the IP. A click and a lander request that resolve to different addresses produce the empty 403. - Meta CAPI sends the click row's IP as `client_ip_address`. TikTok sends it as `ip`. Both are copied from ClickHouse when the event is delivered. Google Measurement Protocol sends no IP field. `vt_vid` and `vt_cid` are `Secure` when the origin connection is TLS, or when `X-Forwarded-Proto` is exactly `https`. Keep that header. The cookies stay readable by the pixel; they are not `HttpOnly`. The compiled range list does not refuse other clients. A request that reaches the port directly is stored as the peer address. Blocking the origin IP so that only Cloudflare can connect is a firewall rule on the server. ## Certificates and SSL mode `VELOTRAK_TLS_DOMAIN` turns on the built-in ACME client and listens on `VELOTRAK_TLS_PORT` (default 443). `VELOTRAK_TLS_CERT_FILE` and `VELOTRAK_TLS_KEY_FILE` load a certificate you already have. The installer's env comments name a Cloudflare Origin CA certificate or the files from a DNS-01 issuance. This program does not talk to a DNS provider, so it cannot do DNS-01 itself. When `VELOTRAK_TLS_DOMAIN` is set, the certificate files are not loaded. The ACME client tries `tls-alpn-01` first: the certificate authority must finish a TLS handshake with this process on 443. It then tries `http-01`: `GET /.well-known/acme-challenge/…` on port 80. The plain HTTP listener is `VELOTRAK_HTTP_PORT`. The installer sets that to 8080. The HTTP handler serves the challenge and then the normal application. It does not redirect other HTTP requests to HTTPS. Orange cloud terminates TLS at Cloudflare, so the `tls-alpn-01` handshake stops there. `http-01` is fetched on port 80 of the public name. The default process is on 8080, and Cloudflare's "Always Use HTTPS" answers port 80 at the edge, so the challenge never reaches the process. Issuance fails. Renewal fails the same way for as long as the name stays proxied. Issuing while the record is DNS-only, then turning the proxy on, leaves the next renewal broken. For an orange-cloud hostname, leave `VELOTRAK_TLS_DOMAIN` unset and install a certificate file. A Cloudflare Origin CA certificate is trusted by Cloudflare's Full (strict) check. A browser that opens the origin directly does not trust that certificate, so visitors should reach the hostname through Cloudflare. A certificate you renew with DNS-01 outside this program works too. Restart the service after the env change. Set the zone's SSL mode to **Full (strict)**. Cloudflare then opens TLS to port 443 and checks the certificate name. **Flexible** opens plain HTTP to the origin. This server answers that HTTP request in place, so Flexible does not loop against Velotrak by itself. Flexible never uses the certificate on 443, and the hop from Cloudflare to the server is unencrypted. Use Full (strict). A redirect you add on port 80 to `https://` the same host will loop in Flexible mode, because Cloudflare keeps fetching the origin over HTTP. The domain Check requests `https:///healthz`, does not follow redirects, and expects the response header `X-Probe-Ack`. `active` means this instance answered. `issuing` means plain HTTP reached this instance and HTTPS did not. `pending_dns` with the detail "a proxy is in between" means the host answered without that header. A challenge page or an interstitial is that case. Pass `Host` through unchanged, and pass `X-Probe` and `X-Probe-Ack`. A hostname that is not on the Domains page is not a tracking host: its landers are sandboxed, and a pixel there cannot read the tracking cookies. See [installation](/docs/installation/). ## Paths the proxy must not change These responses are per visitor. The origin sends `Cache-Control: no-store` on each of them: | Path | What it is | |---|---| | `GET /click/{campaign-id}` | The campaign redirect. The default type is HTTP 302. `meta`, `double_meta`, and `js` are HTTP 200 HTML pages, also `no-store`. | | `GET /dm` | The second hop of a double-meta redirect. | | `GET /go` | Lander to the offer chosen for that click. | | `GET` or `POST /postback/{network-key}` | The affiliate network's server-to-server postback. | | `GET` or `POST /track` | The browser pixel. | | `GET /lp/…` when LP Protect is on, or when the HTML URL contains `click_id` | The protected or macro-substituted lander. | Leave those as the origin sent them. A cache rule that stores them, or that ignores the query string, replays one visitor's redirect, cookie, or lander HTML for the next visitor. Hosted HTML without `click_id`, and other lander files, are `public, max-age=60`. `/velotrak.js` is `public, max-age=300`. Caching those for that long matches the origin. The `js` redirect is an inline script, and an injected pixel is ``. Neither carries a Cloudflare skip attribute. Turn **Rocket Loader** off for the tracking hostname, and turn off **Auto Minify** for HTML and JavaScript there. Those features rewrite the response body this server generated. Bot Fight Mode, Super Bot Fight Mode, Browser Integrity Check, and "I'm Under Attack" serve a JavaScript challenge or a block page. This server has no bypass for that. A network postback is a plain GET or POST from the network's servers. The challenge never completes, and the conversion is never booked. The same challenge drops `/click`, `/go`, `/dm`, `/track`, and `/velotrak.js`. `POST /mcp` is also a non-browser client; a zone-wide fight mode blocks it on any hostname that reaches this process. Turn those features off for the tracking hostname, or skip them for `/click`, `/go`, `/dm`, `/postback`, `/track`, `/lp`, `/velotrak.js`, and `/mcp`. Campaign redirects are HTTP 302, or an HTTP 200 HTML page for the meta and script types. Leave the status code as the origin sent it. There is no WebSocket endpoint in the tracker or the admin, so the zone does not need WebSockets enabled. Cloudflare closes a proxied request at about 100 seconds and returns error 524. This server does not. Backup and restore run inside the admin HTTP request, and a large one can outlast that limit. The admin shell is `Cache-Control: no-cache`. ## Which hostname to proxy Hosted landers, the click link, the postback, and the pixel are paths on a hostname you register. There is no separate lander product-mode. | Hostname | Orange cloud | |---|---| | Tracking domain (campaign link, `/postback`, `/lp`, `/go`, `/track`) | Works for visitor IP when Cloudflare connects straight to Velotrak. Full (strict), a certificate file, no cache on the paths above, bot features off, Rocket Loader and HTML/JS minify off. | | Admin domain (`VELOTRAK_ADMIN_HOST`) | Optional. Same TLS mode, and do not cache it. A restore that runs past the proxy's timeout fails in the browser while the server may still be working. DNS-only avoids that. Give the admin its own hostname when an operator can upload landers. | | A network postback URL | Not its own DNS name. It is `https:///postback/` on the tracking domain. The network's servers must be able to complete that request with no challenge page. | | An external lander on your own site | Outside this process. Velotrak only redirects to that URL. | More on the objects those paths belong to: [flows](/docs/flows/), [landers](/docs/landers/), [conversions](/docs/conversions/), and [CAPI](/docs/capi/). - Q: Does Flexible SSL loop against Velotrak? A: No. Ordinary HTTP is answered as HTTP. Flexible still leaves the hop from Cloudflare to your server unencrypted, and it never uses the certificate on port 443. Use Full (strict). - Q: Will the built-in certificate renew behind orange cloud? A: No. Issuance tries a TLS handshake on port 443 first, which Cloudflare answers itself, then an HTTP check on port 80. The installer listens on 8080. Bring a certificate file instead. Page: https://velotrak.app/docs/cloudflare/ ### Campaigns, sources, offers, and flows A campaign binds a traffic source, a domain, and a flow. The public link is /click/. The flow picks a path, then a lander or an offer, and the click id follows the visitor to the network postback. ## The objects A **traffic source** is where the click comes from. It stores a parameter template (platform, the click-id parameter name, optional cost and zone parameters, and extra parameters) and a postback URL template used when a conversion is booked. Status is active, paused, or draft. An **affiliate network** is who pays you. It has a name, a postback URL template, a network key, a currency, and a status. If you leave the key empty on create, one is generated. A key you type must be 32–128 characters and only letters, digits, `_`, and `-`. Rotate it from the network page or with the MCP tool `rotate_network_key`. The old postback URL stops working immediately. An **offer** belongs to one network. The URL template must be http or https and must contain `{click_id}`. Payout type is `fixed`, `percent`, or `from_postback`. You can set a daily cap. Status is active, paused, or draft. A **lander** is `hosted` (files on this server) or `external` (an http or https URL). See [landers](/docs/landers/). A **flow** is a named set of paths and rules. Paths hold weighted landers and offers. Rules send a visitor to a path or to a safe-page URL. See [flow rules](/docs/flows/). A **campaign** ties one traffic source, one domain, and one flow together. It has a cost model (`cpc`, `cpm`, `cpa`, `manual`, or `auto`), a timezone, and a redirect type (`302`, `meta`, `double_meta`, or `js`). `bind_visitor` is what smart rotation uses to avoid repeating a lander or offer. Only campaigns with status `active` are in the click snapshot. A paused or draft campaign answers `404 campaign not found`. A **domain** is a hostname you registered, with an SSL status and certificate mode. One domain can be the default. ## What a click does The tracking link the admin builds is `https:///click/` plus the query parameters from the source template. The handler is `GET /click/{campaignID}`. The server mints a UUIDv7 click id, sets `vt_vid` (visitor, 365 days) and `vt_cid` (this click, 24 hours), and stores the source's external click id, zone, tokens 1–10, and `fbclid`, `gclid`, `ttclid`, and `msclkid` when they are present. The flow decision runs next. A hosted lander redirects to `/lp//`. An external lander or a direct offer redirects to the expanded URL. `{click_id}` in an offer URL is this click. The lander's link to the offer is `GET /go`, using `cid`, `click_id`, or the `vt_cid` cookie. The campaign's redirect type applies to both the click and `/go`. If the snapshot is not loaded yet, the click returns 503. If the flow is missing or paused, the response is 404. If every lander and offer on the chosen path is paused, the response is 404 and there is no fallback path. Offer daily caps skip capped offers; if every offer on the path is capped, the click is also 404. Paused sources do not drop the campaign by themselves, but a paused source is outside the active snapshot the click uses for source fields. Conversions are a separate request: the network calls [your postback URL](/docs/conversions/). Page: https://velotrak.app/docs/concepts/ ### Flow rules and condition fields A flow evaluates enabled rules by priority and sends the click to a path or a safe page. The built-in fields are 15 visitor properties plus token1–token10. Traffic-source parameters are extra fields. An enabled rule with no condition matches nothing. ## Paths Each path has a name, a rotation of `weight` or `smart`, and lists of landers and offers. Each entry is an id and a weight greater than zero. Exactly one path is the default. If you mark none, the first path becomes the default. The default is where a click lands when no rule matches. Weighted rotation picks a lander and an offer with those weights. Smart rotation, together with the campaign's `bind_visitor` flag, prefers a lander or offer this visitor has not already seen. Offer caps walk the path's offers by sort order and skip a capped offer. The product stores a `cap_fallback` value on the offer, and the editor only offers `next_offer`. Routing does not read `cap_fallback`; a capped path ends in 404 when nothing is left. A rule points at a path or at a safe page. The safe page must be an http or https URL. Rules are checked in ascending priority. Priorities in one flow must be unique. Save the flow as one document (`GET` or `PUT /api/flows/{id}/doc`). The simulator runs the saved document. ## Condition fields Conditions are a mode, `and` (the default) or `or`, and a list of `{ field, op, values }`. These operators are the ones an enabled rule may use. The site's "25 fields" are the 15 names below plus `token1` through `token10`. | Field | Operators on an enabled rule | |---|---| | country, device, language | in, not_in, eq | | os, browser | in, not_in, eq, contains, not_contains, regex | | region, city, isp | in, not_in, eq, contains, not_contains, regex | | ip | in, not_in, eq, contains, not_contains, regex | | referrer, user_agent | contains, not_contains, regex, in, not_in, eq | | hour | between, in, not_in, gt, lt, eq | | weekday | in, not_in, between, eq, gt, lt | | is_bot, is_unique | is, eq, in | | token1–token10, and parameters declared on a traffic source | in, not_in, contains, not_contains, eq, regex, gt, lt | `zone` is always allowed as a source parameter. Other parameter names follow the editor's pattern: a letter, then up to 39 letters, digits, or underscores. ## Values Country is two letters. Language is two or three letters. Device is `mobile`, `tablet`, `desktop`, `bot`, or `unknown` (empty user agent). Hour is 0–23, or `HH:MM` when the operator is `between`. Weekday is 0–6. `between` takes exactly two values. `regex` takes exactly one pattern, and that pattern must compile. `is` takes one JSON boolean, not the string `"true"`. An enabled rule must have at least one condition. At runtime, a rule with no conditions does not match. An enabled rule may contain at most three `regex` conditions in the whole flow; a regex past that budget does not match. A disabled rule can be saved unfinished and is not evaluated. `in` / `eq` / `contains` / `regex` with several values match when any value matches. `not_in` / `not_contains` match when none match. A missing source parameter is an empty value, so a "not in" rule can match a click that simply did not send the parameter. Empty strings inside a value list are ignored. The [concepts](/docs/concepts/) page is how a matched path becomes a redirect. Page: https://velotrak.app/docs/flows/ ### Landing pages in Velotrak A lander is either files Velotrak serves at /lp// or an external URL. Upload a ZIP of up to 25 MiB, or edit HTML, CSS, and JS in the file API. Put index.html at the root so the lander URL has a page. ## Create the lander Choose `hosted` or `external`. An external lander needs an http or https URL in `path_or_url`. A hosted lander stores files on disk under the data directory. Status is active, paused, or draft. A paused lander is not offered to new clicks. You can turn on `inject_js`, which appends the tracker script `/velotrak.js`. LP Protect (`protect_enabled`) is a Pro feature, and Founder follows Pro. On Free the flag is refused. When it is on, the click adds a short-lived `vt_lp` token bound to IP and user agent (5 minutes). A valid visit then gets a session cookie for 2 hours. Anyone else receives an empty 403 page. Preview over plain HTTP can fail to load that page's CSS and JS. Give the admin its own hostname before operators upload pages; a lander opened on the admin host is sandboxed, but a separate admin domain is the isolation the server documents. ## Upload a ZIP `POST /api/landers/{id}/upload` reads one multipart file. The archive may be 25 MiB. The request itself is read up to 26 MiB. Extraction allows 500 entries after junk is stripped, 25 MiB per entry, and 100 MiB uncompressed. Paths that contain `..`, symbolic links, and directory entries are rejected. `__MACOSX` and `.DS_Store` are stripped. A ZIP that is a single folder is unwrapped. `/lp//` serves `index.html` at the lander root. The name is case-sensitive. If the ZIP has no `index.html`, the upload response includes `warning: no_index` and the HTML files it did find. ## Edit files The file API is `GET`, `PUT`, and `DELETE` on `/api/landers/{id}/files` and `/api/landers/{id}/files/`. Text extensions are `.html`, `.htm`, `.css`, `.js`, `.json`, `.txt`, `.svg`, `.xml`, and `.md`. One file may be 2 MiB. The same calls exist as MCP tools (`list_lander_files`, `read_lander_file`, `write_lander_file`, `delete_lander_file`). Writes and deletes ask you to confirm a diff. See [MCP](/docs/mcp/). ## Macros and preview When the lander URL has a `click_id`, these tokens in the HTML are replaced: `click_id`, `campaign_id`, `flow_id`, `lander_id`, `offer_id`, `country`, `device`, `os`, `browser`, `token1`–`token10`, `zone`, and `{offer_link}`. `{offer_link}` becomes `/go` or `/go?cid=...`. Preview is `POST /api/landers/{id}/preview-link`. The relative URL uses `click_id=preview` and sample values (country US, device Mobile, OS iOS, browser Safari), plus `vt_lp` when LP Protect is on. The public page is `GET /lp//`. A missing file is 404. Campaign routing is described under [concepts](/docs/concepts/). Page: https://velotrak.app/docs/landers/ ### Conversions and postbacks The affiliate network calls /postback/ with the click id. Approved, pending, rejected, refunded, and trash are the stored statuses. A click can only be booked by the network that owns the offer it was sent to. ## The URL you give the network Each network has a key. The admin's default postback URL, when you have not set a custom template, is: `https:///postback/?cid={click_id}&payout={payout}&txn_id={transaction_id}&status={status}` The handler accepts `GET` and `POST`. The click id may be named `click_id`, `cid`, `clickid`, or `subid`. Payout may be `payout`, `amount`, or `revenue`. The transaction id may be `txn_id`, `transaction_id`, or `order_id`. You can also send `goal`. If goal is omitted, the offer's default goal is used, or `sale`. An optional signature is the header `X-Velotrak-Signature`: HMAC-SHA256 of the sorted `key=value` pairs, using the network key as the secret. A wrong or unknown network key is 401. ## Statuses Stored statuses are `approved`, `pending`, `rejected`, `refunded`, and `trash`. Common aliases: `sale` becomes approved, `lead` becomes pending, `reject` and `declined` become rejected, `chargeback` and `refund` become refunded. An unknown status is booked as pending and flagged as a status anomaly. A missing or invalid click id is not booked. A postback whose network is not the network of the click's offer returns 403 with `network_mismatch` and is not booked. That includes a second network record you created for the same company, and it includes clicks that happened before you moved the offer. A status change the ledger does not allow returns 200 with `ignored`. Reports treat approved payout as revenue, pending as pending revenue, and trash as trash revenue. Amount, currency, and excess anomalies can force an approved postback down to pending. ## Browser pixel `GET` or `POST /track` is the endpoint used by `/velotrak.js`. It reads `click_id` or the `vt_cid` cookie. The default goal is `lead`. The pixel inserts a conversion; it does not change an existing status. A click accepts at most 10 pixel conversions. ## What you send back to the source When a conversion is booked, an outbox job calls the traffic source's postback URL template. Delivery retries are visible in the outbound log, next to CAPI rows. CAPI itself runs only for an approved conversion with no anomaly. Setup for Meta, TikTok, and Google is the [CAPI page](/docs/capi/). Page: https://velotrak.app/docs/conversions/ ### CAPI for Meta, TikTok, and Google Velotrak sends an approved conversion to Meta, TikTok, or Google from an integration you create in the admin. Free allows one CAPI account per platform. Pro, Team, and Founder do not cap the count. CAPI delivery is not gated by the license. ## Add an integration Create an integration with kind `capi`. Credentials are encrypted in PostgreSQL. The list API does not return them. | Platform | Fields you must set | Endpoint the sender uses | |---|---|---| | meta | `pixel_id` (digits only), `token` | `POST graph.facebook.com/v19.0//events` with the token in the JSON body | | tiktok | `pixel_id`, `token` | `POST business-api.tiktok.com/open_api/v1.3/event/track/` with header `Access-Token` | | google | `measurement_id` (a `G-` id), `api_secret` | `POST www.google-analytics.com/mp/collect` | The admin labels the Meta and TikTok token "Access Token", and the Google fields "Measurement ID" and "API Secret". There is no test-event-code field in the product. `account_id` is optional and defaults to the first credential value. Free's cap is one active CAPI account per platform. Creating or re-enabling another one is refused. Pro, Team, and Founder store `0` for that cap, which means unlimited. The click path still delivers CAPI on every plan, including Free. The [pricing](/pricing/) page says the same thing: CAPI on all three platforms, one account each on Free. ## Which events are sent Only an approved conversion with no anomaly is queued. The goal on the conversion picks the platform event: | Goal | Meta | TikTok | Google (GA4) | |---|---|---|---| | sale | Purchase | CompletePayment | purchase | | lead | Lead | SubmitForm | generate_lead | | install | CompleteRegistration | CompleteRegistration | sign_up | | subscribe | Subscribe | Subscribe | subscribe | | anything else | the goal name | the goal name | the goal name | Value and currency are the payout in the install's main currency. Meta also receives IP, user agent, and an `fbc` value built from the click's `fbclid` (`fb.1..`). It does not send `fbp`. TikTok receives IP, user agent, and `ttclid` when the click had one. Google Measurement Protocol receives value, currency, and a client id. The sender falls back to the click id when it has no separate GA client id. It does not send `gclid`, IP, or user agent to Google. The browser script `/velotrak.js` fires `fbq` and `ttq` with the same event id (a SHA1 of click id, goal, and platform). It does not fire a Google browser tag. Which integration receives the event: the campaign's `capi_account_id`, otherwise the traffic source template's `capi_account_id`, otherwise every active CAPI integration for that platform. The site calls the last case "broadcast". ## Failures The outbox retries a failed send up to 8 attempts, with delays of 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours, then marks the job dead. The HTTP client times out at 10 seconds. A click older than 7 days is stored as `expired` and is not sent. A paused or deleted integration drops the job. Results show in the outbound log (`GET /api/logs/outbound`), including failed, retrying, dead, and expired. The [conversions](/docs/conversions/) page is the postback that creates the approved event. Page: https://velotrak.app/docs/capi/ ### Cost models and allocation Each campaign has a cost model. CPC and CPM write a cost on the click. CPA, manual, and auto write zero at click time. Manual and auto campaigns can receive a daily total that is split across that day's clicks. Automatic pull from ad accounts is a Pro feature. ## Cost on the click `priceClick` runs when the click is logged. - `cpc`: the campaign's `cost_value`. - `cpm`: `cost_value / 1000`. - `cpa`, `manual`, and `auto`: 0 at click time. On a CPC campaign, a cost parameter from the traffic source is kept only up to 10 times the campaign CPC, or up to 5 in the main currency when the campaign CPC is empty. `allow_cost_override` accepts a `cost` query parameter only when `sig` is an HMAC of `campaign id|cost` using the master key. Later allocation does not overwrite a cost that was signed that way. ## Enter a daily total For `cost_model=manual`, the admin and the MCP tools `record_campaign_cost` and `list_campaign_cost` store a spend amount for a calendar day in the campaign timezone. Allocation divides that total by the number of clicks in the local day and writes the share onto each click in ClickHouse. ## Sync from an ad account `cost_sync` is on for Pro, Team, and Founder, and off for Free. An integration with kind `cost` can be `meta`, `tiktok`, or `google`. Sync pulls daily spend into ClickHouse `cost_snapshots`. The integration's `campaign_map_json` maps the external campaign id to a Velotrak campaign. Allocation runs for campaigns whose model is `auto` or `manual`: daily total divided by that day's click count. Trigger it from the admin or with the MCP tool `sync_costs`. Reports read the `cost` column when they compute profit, ROI, CPA, and CPC. See [reports](/docs/reports/). Page: https://velotrak.app/docs/costs/ ### Reports and saved views Reports group the click log by campaign, offer, geography, device, tokens, and time. Free queries the last 15 days and at most 2 dimensions. Pro and above keep full history and 5 dimensions. Each user can save a view. CSV export uses the same query. ## Grouping and metrics The report engine accepts these dimensions: `campaign_id`, `offer_id`, `lander_id`, `flow_id`, `path_id`, `country`, `region`, `city`, `isp`, `device`, `os`, `browser`, `language`, `is_bot`, `token1`–`token10`, `zone`, `hour`, and `day`. The report screen's dimension picker lists `token1`–`token3` only. `token4`–`token10` and `is_bot` still work through the API and through MCP `report_query`. Built-in metrics are clicks, uniques, bot clicks, cost, conversions, pending, rejected, trash, revenue, pending revenue, trash revenue, CR, EPC, ROI, plus profit, CPA, and CPC derived from those. Custom metrics are formulas over the base metrics, up to 12, stored as the `custom_metrics` setting. That feature is Pro (and Team and Founder). Free does not get it. ## Plan limits Free: report lookback is 15 days, and a query may group by at most 2 dimensions. The pricing FAQ says older data is kept; the entitlement limits the query window, it is not a delete job described in the license package. Pro sets lookback and the campaign cap to unlimited (the stored number is 0) and allows 5 group-by dimensions. Team and Founder use the Pro report limits. Team also keeps the audit log, which is separate from reports. A tree drill-down in the UI, when you group by two or more dimensions and drilling is on, requests the first dimension for the child rows. The default query limit in the UI is 1000 rows. `POST /api/reports/export` writes CSV. The UI asks for a BOM with `?bom=1`. ## Saved views and schedules `report_views` stores a name and a JSON config per user. Create and delete them in the report UI or with `list_report_views`, `save_report_view`, and `delete_report_view`. Scheduled email reports need the Pro feature `scheduled_reports`, and the server needs `VELOTRAK_SMTP_*` set. The dashboard (`GET /api/dashboard`) returns totals, a comparison window, a series, top campaigns, and the last backup time. Cost figures in these reports come from the click's cost column. How that column is filled is [cost allocation](/docs/costs/). Page: https://velotrak.app/docs/reports/ ### Connect an AI assistant with MCP An admin creates a token in the Velotrak admin. The client sends Authorization: Bearer vtmcp_… to POST /mcp on the tracker origin. Edits and deletes return a diff and wait for the same call with diff_token. Free tokens are read-only. ## Create a token Only an admin can create MCP tokens (`GET`, `POST`, and `DELETE /api/mcp-tokens`). The plaintext token is shown once. It starts with `vtmcp_`. The server stores a SHA-256 hash, the scope JSON, the creator, and an expiry. If you omit `days`, expiry is 90 days. The maximum is 365. If you omit scopes, the token is `{"reports":{"read":true}}`. The creator must stay an active admin. Disabling that user, or changing their role, makes the token fail authentication. The row can remain in the database. Free and Pro allow one unexpired token (counted for active admin creators). Team stores an unlimited cap. The pricing page describes Team as one token per teammate; the entitlement the app enforces is unlimited. See [plans](/docs/licensing/). Point the client at `POST https:///mcp`. The path is the site root, not under `/admin/`. The header is `Authorization: Bearer `. The protocol version the server announces is `2025-03-26`. ## Scopes and confirmation Scopes are `{ "": { "read": true, "write": true } }`. The admin groups domains as campaigns, offers, landers, flows, sources, networks, domains, reports, and logs; alerts, backups, migration, system, and admin; and the sensitive domains integrations, license, and lander files. A scope of `*` does not cover the sensitive domains, and it never grants tools marked explicit-only (branding changes, restore, and clearing demo data are in that set). A token without write on a domain sees redacted credentials. Write tools require Pro or above (`mcp_write`). On Free they are rejected, except `activate_license`. A destructive call does not run on the first request. The response includes `requires_confirmation`, a `diff_token`, and `expires_in_seconds` of 600. Send the same tool and the same arguments again with that `diff_token`. ## The tool list The table below is generated at build time from `Registry()` in the tracker source. The pricing page and the homepage still say 90 tools. This table is the list the registry and the CI check keep in sync with the tools the server actually registers. One admin route has no tool: `PATCH /api/integrations/{id}` updates an integration, and the registry only has create, delete, list, and `sync_costs`. Page: https://velotrak.app/docs/mcp/ ### Backup and restore Backups are logical dumps of PostgreSQL, kept under the data directory, seven copies. ClickHouse click history is not in the file. Restore replaces rows in one transaction after you send the confirmation word, and it does not include master.key. ## What is in the file The backup covers the PostgreSQL tables the tracker uses for configuration, users, the conversion ledger, tokens, and the audit log. `schema_migrations`, `license_runtime`, and `outbox` are not replaced on restore. ClickHouse is not in the logical backup. The project treats it as a rebuildable copy of the click log. After a disaster, configuration and booked conversions come back from PostgreSQL. Click detail depends on whatever ClickHouse still has, plus what you can reconcile with the ad platforms. The file contains password hashes, license keys, and integration credentials in their encrypted form. It does not contain `master.key`. That file lives in the data directory (`/var/lib/velotrak/master.key` on an install from the script). Without it, stored credentials cannot be decrypted. Back up the data directory, or at least `master.key`, next to the logical backup. The backup directory is `VELOTRAK_DATA_DIR/backups/`, mode 0700, files mode 0600. ## Create one The process takes a backup about a minute after start, then checks hourly, and writes one when the newest file is at least 24 hours old. It keeps the 7 newest. The admin backup page and MCP can create one immediately: `list_backups` and `create_backup`. `create_backup` is an admin action. API keys cannot call the backup routes; a write-scoped API key is only an operator. Use an MCP token that has the backups scope. ## Restore `POST /api/backups/restore` requires `"confirm": "RESTORE"`. The server writes a pre-restore snapshot first, then reloads rows in one transaction and checks the row counts against the manifest. MCP `restore_backup` is explicit-only: a wildcard write scope does not grant it, and it uses the same diff confirmation as other destructive tools. Restoring an older file brings back that file's session generation. The operator notes suggest signing in again or changing the password after a restore from before an upgrade that rotated sessions. The [install](/docs/installation/) page lists the directories to copy if you move the server. Page: https://velotrak.app/docs/backup/ ### Plans, limits, and offline grace Free is $0, Pro is $49 a month or $490 a year, Team is $99 a month or $990 a year, and Founder is $399 once. Clicks are not metered. A lapsed subscription has 7 days of read-only paid access, then Free. A paid license that cannot phone home for 30 days stays fully paid. ## Prices Checkout charges the amounts in `prices.ts`, which the [pricing](/pricing/) page shows. Annual prices are the yearly total. The cards also show a per-month equivalent. | Plan | Charged | |---|---| | Free | $0 | | Pro | $49 every month, or $490 once a year (shown as $41/mo) | | Team | $99 every month, or $990 once a year (shown as $83/mo) | | Founder | $399 once, presale, limited to 100 on the pricing page | The license is the software. The server is yours. Activate in the admin under License, or with the MCP tool `activate_license` (this tool is allowed on Free). `license_status` and `license_heartbeat` are the other license tools. ## What each plan unlocks Numbers come from the entitlement struct. A stored `0` means unlimited. Founder is the Pro struct with the plan name `founder`. | | Free | Pro and Founder | Team | |---|---|---|---| | Active campaigns | 3 | unlimited | unlimited | | Report lookback | 15 days | unlimited | unlimited | | Report dimensions | 2 | 5 | 5 | | Campaigns per import | 20 | unlimited | unlimited | | CAPI accounts per platform | 1 | unlimited | unlimited | | Users | 1 | 3 | unlimited | | MCP tokens | 1 | 1 | unlimited in code | | MCP write, custom metrics, cost sync, alert auto-pause, scheduled reports, Telegram and webhook, LP Protect, branding | off | on | on | | Operator and viewer roles, audit log, API keys, Powered-by toggle | off | off | on | Pro users are admins only, because roles are a Team flag. The pricing line "up to 3 users (admins)" matches that. Team's pricing line says one MCP token per teammate. The Team entitlement sets the token cap to 0, which the code treats as unlimited. The app enforces the entitlement. Email alert rules are not behind the notifications flag. Telegram and webhook delivery, and auto-pause from an alert, are. Free's pricing line says "email alerts", which matches the email path not being plan-gated. Vendor install caps, enforced when a license is activated, are 1 install for Pro and Founder and 3 for Team, multiplied by seats. The pricing page states the same install counts. Founder licenses are written with `update_until` one year after creation. The admin license payload includes that timestamp. The pricing page calls this 12 months of updates. This tree does not show the in-app updater refusing a download after that date. ## When the license cannot be reached Nothing in the entitlement package is allowed to touch the click, postback, or CAPI delivery path, and nothing is metered by traffic volume. Limits apply when someone creates or enables something. The status machine has two clocks: - After `period_end`, the state is grace for 7 days. The plan name stays. Create and enable gates fall back to Free (3 active campaigns, no MCP write, and the other Free caps). Report lookback, report dimensions, and the Team audit log stay at the paid values. After those 7 days the state is expired and the plan is Free. - If the last successful heartbeat is more than 30 days ago, the state is unverified. Unverified is still paid in full. That is the offline window the pricing FAQ calls a 30-day offline grace. It is not the same thing as the 7-day grace after the paid period ends. A revoked license is Free. [Team roles](/docs/team/) and [backup](/docs/backup/) are unchanged by this page's prices. Page: https://velotrak.app/docs/licensing/ ### Import from Binom or Keitaro Velotrak imports its own export and JSON from Binom or Keitaro. There is no Voluum importer in the product. The Binom and Keitaro adapters bring paths, offers, and external landers. They do not import flow rules. Free stops at 20 campaigns in one import. ## Export what you have `GET /api/export` (MCP `export_config`) writes traffic sources, networks, offers, lander metadata, flows (paths, weights, rotation, rules), and campaigns. Network keys are replaced with a `NETWORK_KEY` placeholder. CAPI and other integration credentials are not included. Hosted lander files are not included. Copy those files yourself; the [landers](/docs/landers/) page is the upload. ## Import `POST /api/import` and MCP `import_config` accept format `velotrak`, `binom`, or `keitaro`. The Binom adapter builds one flow per campaign from that campaign's paths. Landers come in as external URLs. Flow rules are not parsed. The Keitaro adapter turns streams into paths and landers into external URLs. It does not import rules either. There is no Voluum adapter in the importer. Voluum appears as a traffic-source template name, not as a file you can upload. Free's `max_import_campaigns` is 20. The pricing FAQ says campaigns past the three active ones land paused, so the import can keep them without turning them on. Pro, Team, and Founder store 0 for that cap, which means the import is not capped by this field. Re-importing does not reuse the old network key; the export placeholder is filled again. Update the postback URL at the network after each import. ## Templates and demo data `GET /api/templates` lists built-in source and network templates. `POST /api/templates/apply` applies one. `generate_demo` and `clear_demo` fill or remove demo data. Both are admin actions, and `clear_demo` is explicit-only on MCP: a wildcard scope does not grant it, and it asks for diff confirmation. Compare that with a from-scratch setup on the [concepts](/docs/concepts/) page. The [pricing](/pricing/) page states the import cap in the Free plan line. Page: https://velotrak.app/docs/migration/ ### Users, roles, and API keys Roles are admin, operator, and viewer. Operator and viewer exist only on Team. API keys are a Team feature and are either read-only or read-write, and read-write is capped at operator. Disabling a user ends their sessions immediately. ## Roles The three role names are `admin`, `operator`, and `viewer`. An admin or an operator can write. A viewer is read-only: mutating requests are rejected except a short allowlist of read-style POSTs (report query and export, flow simulate, lander preview link). The admin UI describes it as admin for full access, operator for delivery configuration, viewer for read-only. Pro does not enable the roles feature, so extra users on Pro are admins, up to the cap of 3. Team turns roles on and does not cap the user count. You cannot change your own role or status, so the last admin cannot lock themselves out. A password is at least 8 characters and at most 72 bytes. Changing your own password keeps the current session and invalidates the others. Viewers, and MCP tokens without write on that domain, see a masked network key (`••••` plus the last 4 characters). Webhook URLs and source postback templates are masked to the host. A viewer does not get the control that copies the postback link. Config export, which includes source postback templates, is operator and above. ## API keys API keys require Team (`api_keys`). Scopes are `["read"]` or `["read","write"]`. Omitting scopes creates a read-only key. A read key acts as a viewer. A read-write key acts as an operator at most. It cannot call users, API keys, backups, MCP tokens, the audit log, branding and general settings, license activate, software update, or demo data. Those stay admin routes and return 403. A key whose creator is not an active user stops working. ## Disabling someone `DELETE /api/users/{id}` or `PATCH` with `status: "disabled"` bumps the session generation. Existing logins fail on the next request. Their API keys stop. Their MCP tokens fail because the creator is no longer an active admin. Scheduled reports they owned stop because the scheduler joins active users. The rows are not necessarily deleted. Re-enabling the user does not restore old sessions; they sign in again. Audit log is the Team feature that records who changed what. MCP tokens are covered on the [MCP](/docs/mcp/) page, and the caps are on [plans](/docs/licensing/). Page: https://velotrak.app/docs/team/ ### Troubleshooting Velotrak A click 404s when the campaign or flow is not active, or when the path has no active lander and offer. A postback 403s when the network key does not belong to the click's offer. LP Protect answers everyone else with an empty 403. ## Click responses `GET /healthz` returns `{"status":"ok"}` when the process is up. The installer waits on that URL. | What you see | Cause in the click handler | |---|---| | 503 `not ready` | The in-memory snapshot is not loaded yet. | | 404 `campaign not found` | The id is unknown, or the campaign is not `active`. Paused and draft campaigns are omitted from the snapshot. | | 404 `flow not found` | The flow is missing or not `active`. | | 404 `no available offer` | The path's landers or offers are all paused, or every offer is over its daily cap. There is no fallback path. | | 404 `no target` | The decision produced nothing to redirect to. | | 404 `unknown click` on `/go` | The click id is not in the lookup. | The admin warns before you copy a link when the campaign is inactive, the flow is empty or paused, or the offers or landers are paused. ## Postbacks and pixels Unknown network key: 401. Right key, wrong network for that click: 403 `network_mismatch`, nothing booked, no CAPI. The inbound log shows rejected. A hosted lander on a hostname you did not register is sandboxed, so its pixel cannot read the tracking cookies. Register the host on the Domains page and make the proxy pass `Host` through. A proxied hostname that challenges postbacks, or that stores the edge address instead of the visitor, is covered in [Cloudflare](/docs/cloudflare/). If country, region, and city are empty after install, the GeoIP download may have failed. The installer looks for `/var/lib/velotrak/geoip/dbip-city.mmdb` and warns when it cannot fetch one. ## LP Protect and login LP Protect without a valid `vt_lp` token returns an empty 403. The entry token lasts 5 minutes and is tied to IP and user agent. The session after that lasts 2 hours. The feature is Pro. On plain HTTP, a preview of a protected page can fail to load its CSS and JS. If every admin session died after an upgrade, the master key may have been created for the first time (older builds used an empty key, and those sessions were invalidated). New installs from the script already set a master key. Losing `master.key` does not stop clicks. It does stop decryption of integration credentials until you enter them again. Keep it with your [backups](/docs/backup/). More on the happy path: [installation](/docs/installation/), [flows](/docs/flows/), [conversions](/docs/conversions/). - Q: Does tracking stop when the license server is down? A: No. Click, postback, and CAPI delivery are outside the license checks. A paid license with no heartbeat for 30 days stays paid. After the subscription period ends, create actions fall back to Free limits for 7 days, then the plan becomes Free. - Q: Why is my postback ignored? A: A wrong network key is 401. A key for a different network than the offer the click used is 403 network_mismatch and is not booked. A status the ledger will not move to returns 200 ignored. Page: https://velotrak.app/docs/troubleshooting/ ## Articles ### How to install Velotrak on a Linux server Install the self-hosted Velotrak ad tracker with one command on Linux. What the installer does, the server size, and how an upgrade run behaves. Velotrak installs on a Linux server with one command, run as root: `curl -fsSL https://velotrak.app/install.sh | sudo bash`. The installer is the same script published at that URL. It is for x86_64 and arm64, it refuses to run if you are not root or if systemd or curl is missing, and it warns when the machine has under about 4 GB of RAM. The [installation guide](/docs/installation/) covers the wizard, domains, TLS, and upgrades. ## What you need The marketing site lists two sizes. The floor is 2 vCPU and 4 GB, described as enough for at least 800 clicks per second (about 69 million a day). The recommended size is 4 vCPU and 8 GB. A VPS from about $10 a month is what the site quotes for the floor. The license does not include that server. ## What the installer does The script header, which you can read at [velotrak.app/install.sh](https://velotrak.app/install.sh), describes a fresh install as three steps: 1. If Docker is missing, it installs Docker from get.docker.com, then starts PostgreSQL and ClickHouse with Docker Compose under `/opt/velotrak/stack`. Those databases listen on 127.0.0.1 only, with generated passwords. 2. It downloads the release binary for this machine from GitHub releases (`velotrak/velotrak`) and checks the SHA-256 against `checksums.txt`. 3. It writes `/opt/velotrak/velotrak.env` (database URLs and a generated master key) and a systemd unit, starts the service, and waits until it answers. Velotrak itself runs as a normal binary, not as a container. The release list is at [github.com/VeloTrak/Velotrak/releases](https://github.com/VeloTrak/Velotrak/releases). ## After it is up The site's setup section is five steps: install, set timezone and currency, connect traffic sources (30+ source templates and 25+ affiliate templates), build campaigns and a flow (25 condition fields), then attach CAPI. Meta, TikTok and Google CAPI are on every plan, including Free, with one account per platform on Free. Clicks and conversions stay in the databases on this server. You can export them in full. Product telemetry is off unless you turn it on. ## Upgrades and your own databases Run the same command again to upgrade. The script keeps the previous binary as `velotrak.old` and leaves the env file, the passwords and the data alone. To pin a version: ```bash curl -fsSL https://velotrak.app/install.sh | sudo VELOTRAK_VERSION=v1.2.3 bash ``` Replace `v1.2.3` with a tag that exists on the releases page. To bring your own PostgreSQL and ClickHouse instead of the bundled ones: ```bash curl -fsSL https://velotrak.app/install.sh | sudo VELOTRAK_EXTERNAL_DB=1 bash ``` That skips Docker. You then set the database URLs in the env file. Migrations are built into the binary. ## Prices, if you outgrow Free Free is $0, with unmetered clicks, up to 3 active campaigns, and reports on the last 15 days. Pro is $49 a month or $490 a year (shown as $41/mo). Team is $99 a month or $990 a year (shown as $83/mo). None of those prices change with click volume. The [pricing page](/pricing/) lists both intervals, and the [alternatives](/alternatives/) pages compare this with Voluum, RedTrack, Binom, Keitaro and BeMob using those vendors' own pages. - Q: What server does the Velotrak installer expect? A: Linux with systemd, root, and curl. The script accepts x86_64 and arm64. It warns when RAM is under about 4 GB. The site lists 2 vCPU / 4 GB as the floor and 4 vCPU / 8 GB as the recommended size. - Q: Does tracking stop if the license server cannot be reached? A: No. The site says licensing is separate from the click path, with a 30-day offline grace. - Q: Where are clicks stored after install? A: On that server. Unless you set VELOTRAK_EXTERNAL_DB=1, the installer starts PostgreSQL and ClickHouse and binds them to 127.0.0.1. Clicks go to ClickHouse. The ledger stays in PostgreSQL. Telemetry is off by default. Page: https://velotrak.app/blog/install-on-linux/ ## Homepage FAQ ### Is self-hosting a hassle? What server do I need? One install command (curl … | sudo bash) sets up Velotrak with PostgreSQL and ClickHouse. Minimum: 2 vCPU / 4 GB (floor tier, sized for ≥800 clicks/s — about 69M/day); recommended: 4 vCPU / 8 GB. A VPS from about $10/mo runs the floor tier, and the five-step wizard needs no config-file editing. ### If my server loses internet, or licensing breaks, does tracking stop? No. Licensing is separate from the click path, with a 30-day offline grace. ### What does the free plan include, and where does it stop? Clicks are never metered on any plan. Free runs up to 3 active campaigns, reports on the last 15 days (older data is kept), and includes CAPI on all three platforms with 1 account each. When you hit a limit, the app shows exactly what Pro or Team unlocks — upgrade then. ### I'm on another tracker. How painful is migration? Free imports up to 20 campaigns at a time — beyond 3 they land paused, so nothing is lost. Pro and above import without limits, with mappings built in. ### Does any of my data reach Velotrak's servers? No. Data stays in your own databases, telemetry is off by default, and full export is always available. ### How should I read the performance figures? 3,071 clicks/s was load-tested on a shared 4-vCPU VM: the app, PostgreSQL, ClickHouse and the load generator all ran on the same box, and 92,135 clicks were sent with zero lost — about 265M clicks a day. ### What exactly is the $399 Founder lifetime plan? All Pro features for life on 1 install, with 12 months of updates included. Limited to 100. ### Can I look before I commit? Yes. Open the live demo — the account's email and password are already filled in, just click Sign in; build campaigns, edit flows and run reports freely (the data resets daily), no sign-up. Or run the free plan on real traffic. No card either way. ### If I let an AI operate through MCP, could it mess things up? No. Deletes and edits need two-step confirmation: diff first, execute after you approve. Permissions are per area.