Is there an async client?

Not today: the client is synchronous and uses the standard library only. In FastAPI or Starlette, hand the call to a background task, which runs it in a thread after the response — the page shows how.

Which frameworks can read the trackID?

track_id_from_request reads Django requests (the Cookie header), Flask and Starlette / FastAPI requests (their cookies), and any object with a headers mapping. It returns None when the visitor did not come from an ad.

What if the visitor did not come from an ad?

Pass None. The sign-up is still recorded, and the user is organic: no campaign is credited.

Will a retry count a purchase twice?

No. Each call mints its event ids once and retries the identical body, and a purchase is also keyed on its transaction_id, so the same payment reported twice is stored once.

SDKs

Python server SDK

Report sign-ups and purchases from a Python backend with the traqio package, and tie each one to the ad click it came from. Django, Flask, FastAPI.

Open in:ChatGPT Claude Perplexity

traqio is the Traqio SDK for Python backends — the server half of Traqio's web SDK. The conversion that counts on a website — a sign-up, a subscription, a purchase — happens on your backend, where the user id is known. This package reports it with the trackID, the ad click id that @traqio/web kept in first-party storage since the landing page, and Traqio credits the campaign that brought the user — deterministically, by that click's id. Standard library only; Django, Flask, FastAPI or any other framework.

Not on PyPI yet — early access

Package traqio · version 0.1.0The SDK packages are not on their public registries yet. To integrate today, ask for the build: hello@traqio.appHow far it is proven: Unit-tested, and run end-to-end against a running Traqio API: sign-up with a trackID → attributed.

Requirements#

Python 3.9 or later. No dependency; typed (py.typed).
A server key for the product (tq_sk_…). Neither the app's SDK key nor a web key works here.
@traqio/web on the site, and ads pointing at tracking links with a website destination — that is how the trackID reaches your sign-up form.

Set up#

Create a server key#
In the console, open Integrations → SDK and create a server key. It is shown once: put it in the backend's environment, never in code or in a page. Traqio keeps only a fingerprint of it; a lost key is replaced by a new one, and the old one revoked.
.env
```
TRAQIO_SECRET_KEY=tq_sk_...
```

Install the package#

pip install traqio

Until the package is on PyPI, install the wheel we send you:

# the file you received, committed inside the backend's repository
pip install ./vendor/traqio-0.1.0-py3-none-any.whl

Create the client#

import os
from traqio import Traqio

# One client per process. The key comes from the server's environment, never from code.
traqio = Traqio(os.environ["TRAQIO_SECRET_KEY"])

The client holds no connection: one per process is enough. It refuses a web key (tq_web_…).

Call signup() once, where the account is created. @traqio/web writes the trackID in the traq_click cookie on your own domain, so the browser sends it with the sign-up request:

from traqio import TraqioError, track_id_from_request

def signup(request):
    user = User.objects.create_user(...)
    try:
        traqio.signup(str(user.pk), track_id_from_request(request))
    except TraqioError as error:
        logger.warning("traqio: %s", error)  # never fail the sign-up itself
    return redirect("/welcome")

from flask import request
from traqio import track_id_from_request

@app.post("/signup")
def signup():
    user = create_user(request.form)
    traqio.signup(str(user.id), track_id_from_request(request))
    return redirect("/welcome")

from fastapi import BackgroundTasks, Request
from traqio import track_id_from_request

@app.post("/signup")
async def signup(request: Request, background: BackgroundTasks):
    user = await create_user(await request.json())
    # The client is synchronous: a background task runs it in a thread, after the response.
    background.add_task(traqio.signup, str(user.id), track_id_from_request(request))
    return {"id": user.id}

If the backend is on another domain than the site, the cookie does not reach it: send Traqio.getTrackId() from the browser with the form instead. The sign-up is the moment the user is acquired; the last click before it, inside your attribution window, gets the credit.

Track the conversions#

traqio.track(
    str(user.pk),
    "purchase",
    value=49,
    currency="EUR",
    transaction_id=payment_intent.id,  # one payment, one row — whoever reports it
    store="stripe",
)

Conversions follow the user: they are credited to the campaign that acquired them.

What the response tells you#

result = traqio.signup(str(user.pk), track_id)

result.track_id                 # "matched" | "unknown" | "expired" | "claimed" | "refused" | None
result.acquired                 # True: the sign-up is recorded
result.attribution.network      # "meta", "tiktok"… or "organic"
result.attribution.campaign_id  # the campaign that brought the user

track_id	Meaning
`matched`	The click is now this user's. A retry answers matched again.
`unknown`	No click of this product has that id — a typo, another product's link, or a value @traqio/web did not write.
`expired`	The click is older than the product's attribution window.
`claimed`	Another user, or an app install, already owns that click. A click credits one identity.
`refused`	The click failed an anti-fraud rule (it came through an anonymising network). It is counted, never credited.

What it does today, and what it does not#

	Today
Tie a sign-up to its click, and say who was credited	Yes — in the response
Record purchases with value, currency and payment id, deduplicated	Yes
Leave your apps' installs, revenue and ROAS untouched	Yes — never attached to an app install
Show web conversions in the console's reports	Yes — per campaign, beside installs
Send web conversions to Meta or TikTok	Not yet

Conversions sent here appear in Live events, marked as not matched to an install — expected for a website. A sign-up credited to a campaign is counted in the ROAS report as a web conversion of that campaign, beside its installs, and the response of each call gives you the attribution at once.

Errors and retries#

A network error, a timeout, a 429 or a 5xx is retried — twice by default, with the same body, so nothing is counted twice. A 4xx (wrong or revoked key, invalid payload) is not retried. Both end as a TraqioError:

from traqio import TraqioError

try:
    traqio.signup(str(user.pk), track_id)
except TraqioError as error:
    # error.status: 401 = wrong or revoked key, 400 = invalid payload, None = network
    logger.warning("traqio: %s (status %s)", error, error.status)

Report after your own write

Call Traqio once the account or the payment is saved, and never let a Traqio error fail it.

API reference#

Traqio(…)

Traqio(
    secret_key,            # the server key, tq_sk_… — required
    endpoint="https://api.traqio.app",
    timeout=10.0,          # seconds per attempt
    max_retries=2,         # after a network error, a 429 or a 5xx
    transport=None,        # a custom transport (proxies, tests)
)

Method	What it does
`signup(user_id, track_id=None, events=())`	Reports the sign-up — the acquisition — with its trackID. The first one is kept.
`track(user_id, name, *, value, currency, transaction_id, store, event_id, track_id)`	Records one conversion of a known user.
`send(user_id, *, track_id, signup, events)`	The raw call behind both, for several events at once.
`track_id_from_request(request)`	The trackID from a Django, Flask or Starlette request, or None.
`track_id_from_cookie_header(header)`	The same, from a raw Cookie header.

Proof so far

Tested on Python 3.9 and 3.11, including the real HTTP transport, and run end to end against a running Traqio API: a sign-up carrying a trackID came back matched with its campaign, an unknown click was told unknown, a wrong key was refused. Not yet run in a customer's production backend.

Frequently asked questions#

Is there an async client?: Not today: the client is synchronous and uses the standard library only. In FastAPI or Starlette, hand the call to a background task, which runs it in a thread after the response — the page shows how.
Which frameworks can read the trackID?: track_id_from_request reads Django requests (the Cookie header), Flask and Starlette / FastAPI requests (their cookies), and any object with a headers mapping. It returns None when the visitor did not come from an ad.
What if the visitor did not come from an ad?: Pass None. The sign-up is still recorded, and the user is organic: no campaign is credited.
Will a retry count a purchase twice?: No. Each call mints its event ids once and retries the identical body, and a purchase is also keyed on its transaction_id, so the same payment reported twice is stored once.

Last updated October 16, 2026