Debug API

Dry-run attribution

POST /v1/debug/attribution

Test attribution matching without recording anything. Pass the same fingerprint data the SDK would send, and Trace returns which click (if any) would match — without creating an install record.

This is useful for:

• Verifying your short links are set up correctly
• Debugging why an attribution didn’t match
• Testing the attribution flow in CI/CD

Request body

{
  "apiKey": "tr_live_xxxxxxxxxxxx",
  "fingerprint": {
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (Linux; Android 14; Pixel 8)",
    "platform": "ANDROID",
    "osVersion": "14",
    "deviceModel": "Pixel 8",
    "screenWidth": 1080,
    "screenHeight": 2400,
    "screenDensity": 2.75,
    "locale": "en_US",
    "timezone": "America/New_York",
    "appVersion": "1.0.0",
    "sdkVersion": "1.0.0"
  },
  "installReferrer": "utm_source=google&trace_click_id=abc123",
  "clickId": null
}

Field	Type	Required	Description
apiKey	string	yes	Your app’s API key
fingerprint	object	yes	Device fingerprint (same shape the SDK sends)
installReferrer	string	no	Android install referrer string
clickId	string	no	Explicit click ID from a deep link

Fingerprint fields

Field	Type	Required	Description
ipAddress	string	yes	Client IP address
userAgent	string	yes	Browser or app User-Agent string
platform	string	yes	ANDROID or IOS (case-sensitive)
osVersion	string	no	OS version string (e.g. 14, 17.0)
deviceModel	string	no	Device model (e.g. Pixel 8, iPhone15,2)
screenWidth	int	no	Screen width in pixels
screenHeight	int	no	Screen height in pixels
screenDensity	float	no	Screen density / DPI
locale	string	no	Device locale (e.g. en_US)
timezone	string	no	IANA timezone (e.g. America/New_York)
appVersion	string	no	App version string
sdkVersion	string	no	SDK version string

Response

{
  "attributed": true,
  "method": "INSTALL_REFERRER",
  "installId": null,
  "clickId": "abc123",
  "campaignId": "summer_sale",
  "deepLinkPayload": {
    "deepLinkPath": "/product/123",
    "deepLinkParams": {"color": "blue"},
    "isDeferred": true
  },
  "metadata": {}
}

The response shape is identical to a real attribution response, except installId is always null (since no install is recorded).

Attribution methods

The method field tells you how the match was made:

Method	Description
INSTALL_REFERRER	Matched via the Android install referrer string containing a trace_click_id
CLICK_ID	Matched via an explicit click ID passed by the SDK
FINGERPRINT	Probabilistic match based on device signals (screen, OS, locale, timezone)
ORGANIC	No match found — the install would be recorded as organic

Example

CLI

# Minimal — required fields only
trace debug attribution \
  --ip-address 203.0.113.42 \
  --user-agent "Mozilla/5.0 (Linux; Android 14; Pixel 8)" \
  --platform ANDROID

# Full fingerprint for accurate scoring
trace debug attribution \
  --ip-address 203.0.113.42 \
  --user-agent "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)" \
  --platform IOS \
  --device-model "iPhone15,2" \
  --os-version "17.0" \
  --screen-width 1179 \
  --screen-height 2556 \
  --screen-density 3.0 \
  --locale en-US \
  --timezone America/New_York

# Match against a specific click
trace debug attribution \
  --ip-address 203.0.113.42 \
  --user-agent "Mozilla/5.0 (Linux; Android 14)" \
  --platform ANDROID \
  --click-id abc123

The attribution command always outputs JSON since the scoring data is structured.

curl

curl -X POST https://api.traceclick.io/v1/debug/attribution \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "tr_live_xxxxxxxxxxxx",
    "fingerprint": {
      "ipAddress": "203.0.113.42",
      "userAgent": "Mozilla/5.0 (Linux; Android 14; Pixel 8)",
      "platform": "ANDROID",
      "osVersion": "14",
      "deviceModel": "Pixel 8",
      "screenWidth": 1080,
      "screenHeight": 2400,
      "screenDensity": 2.75,
      "locale": "en_US",
      "timezone": "America/New_York",
      "appVersion": "1.0.0",
      "sdkVersion": "1.0.0"
    }
  }'

Tip

Enable debug = true in your SDK’s TraceConfig to see the exact fingerprint being sent. Copy it from Logcat (Android) or Console (iOS) and paste it into the debug endpoint to verify matching.

Caution

This endpoint is rate-limited to 30 requests per minute per IP address.

---

Reset sandbox data

POST /v1/debug/reset

Clear all sandbox attribution data for your app. Useful for resetting state between test runs. Optionally scope the reset to a specific IP address.

Request body

{
  "ipAddress": "203.0.113.42"
}

Field	Type	Required	Description
ipAddress	string	no	Only reset data associated with this IP. Omit to reset all sandbox data.

Response 200 OK

{
  "reset": true
}

Example

CLI

# Reset all sandbox data
trace debug reset

# Reset data for a specific IP only
trace debug reset --ip-address 203.0.113.42

curl

# Reset all sandbox data
curl -X POST https://api.traceclick.io/v1/debug/reset \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

# Reset for a specific IP
curl -X POST https://api.traceclick.io/v1/debug/reset \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"ipAddress": "203.0.113.42"}'

Note

This only affects sandbox/debug data. Production attribution records are not modified.