Linktree debug bundle

Linktree Debug Bundle

Overview

This debug bundle collects diagnostic evidence from Linktree link-in-bio API integrations for troubleshooting profile rendering, link analytics, and webhook delivery issues. It captures OAuth token validity, profile metadata retrieval, individual link status checks, click analytics availability, and webhook endpoint health. The resulting tarball gives support engineers the data needed to diagnose broken links, missing analytics events, profile sync failures, and API permission issues without requiring Linktree admin access.

Prerequisites

• curl, jq, tar installed
• LINKTREE_API_KEY set (OAuth bearer token from Linktree developer portal)

Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-linktree-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Environment ===" > "$BUNDLE/environment.txt"
echo "API Key: ${LINKTREE_API_KEY:+SET (redacted)}" >> "$BUNDLE/environment.txt"
echo "Node: $(node -v 2>/dev/null || echo 'not installed')" >> "$BUNDLE/environment.txt"
echo "Timestamp: $(date -u)" >> "$BUNDLE/environment.txt"

# API connectivity — user profile
echo "=== API Health ===" > "$BUNDLE/api-health.txt"
curl -sf -o "$BUNDLE/api-health.txt" -w "HTTP %{http_code} in %{time_total}s\n" \
  -H "Authorization: Bearer ${LINKTREE_API_KEY}" \
  "https://api.linktree.com/v1/user" 2>&1 || echo "UNREACHABLE" > "$BUNDLE/api-health.txt"

# Profile links enumeration
echo "=== Links ===" > "$BUNDLE/links.json"
curl -sf -H "Authorization: Bearer ${LINKTREE_API_KEY}" \
  "https://api.linktree.com/v1/links" \
  >> "$BUNDLE/links.json" 2>&1 || echo '{"error":"FAILED"}' > "$BUNDLE/links.json"

# Link click analytics (last 7 days)
echo "=== Analytics ===" > "$BUNDLE/analytics.json"
curl -sf -H "Authorization: Bearer ${LINKTREE_API_KEY}" \
  "https://api.linktree.com/v1/analytics?period=7d" \
  >> "$BUNDLE/analytics.json" 2>&1 || echo '{"error":"ANALYTICS_FAILED"}' > "$BUNDLE/analytics.json"

# Recent logs
echo "=== Recent Logs ===" > "$BUNDLE/app-logs.txt"
tail -100 /var/log/linktree-sync/*.log >> "$BUNDLE/app-logs.txt" 2>/dev/null || echo "No sync logs found" >> "$BUNDLE/app-logs.txt"

# Rate limit status
echo "=== Rate Limits ===" > "$BUNDLE/rate-limits.txt"
curl -sI -H "Authorization: Bearer ${LINKTREE_API_KEY}" \
  "https://api.linktree.com/v1/user" 2>/dev/null | grep -i "x-rate\|retry-after\|x-ratelimit" >> "$BUNDLE/rate-limits.txt" || echo "No rate limit headers" >> "$BUNDLE/rate-limits.txt"

# Package versions
echo "=== Dependencies ===" > "$BUNDLE/deps.txt"
npm ls 2>/dev/null | grep -i linktree >> "$BUNDLE/deps.txt" || echo "No Linktree npm packages found" >> "$BUNDLE/deps.txt"

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Analyzing the Bundle

tar -xzf debug-linktree-*.tar.gz
cat debug-linktree-*/environment.txt     # Verify API key is set
cat debug-linktree-*/api-health.txt      # Check HTTP status and latency
jq '.links | length' debug-linktree-*/links.json       # Count active links
jq '.totalClicks' debug-linktree-*/analytics.json      # Verify analytics data

Common Issues

Symptom	Check in Bundle	Fix
401 Unauthorized	environment.txt shows key NOT SET	Generate new API key in Linktree Developer Settings
Profile returns but links empty	links.json has empty array	Ensure links are published (not draft); check link visibility settings
Analytics returns 403	analytics.json shows permission error	Analytics API requires Pro plan or higher; upgrade Linktree subscription
Click counts stuck at zero	analytics.json shows totalClicks: 0	Analytics lag up to 24h; verify links have tracking enabled
429 rate limited	rate-limits.txt shows retry-after	Linktree allows 100 req/min; implement request queuing with backoff
Webhook not firing	App logs show no delivery attempts	Verify webhook URL in Linktree admin; check SSL cert validity on receiving endpoint

Automated Health Check

async function checkLinktreeHealth(): Promise<{
  status: string;
  latencyMs: number;
  profileOk: boolean;
  linkCount: number;
  analyticsAvailable: boolean;
}> {
  const apiKey = process.env.LINKTREE_API_KEY;
  const headers = { Authorization: `Bearer ${apiKey}` };
  const start = Date.now();

  const profileRes = await fetch("https://api.linktree.com/v1/user", { headers });
  const linksRes = await fetch("https://api.linktree.com/v1/links", { headers });
  const analyticsRes = await fetch("https://api.linktree.com/v1/analytics?period=7d", { headers });

  let linkCount = 0;
  if (linksRes.ok) {
    const data = await linksRes.json();
    linkCount = data.links?.length ?? 0;
  }

  return {
    status: profileRes.ok ? "healthy" : "degraded",
    latencyMs: Date.now() - start,
    profileOk: profileRes.ok,
    linkCount,
    analyticsAvailable: analyticsRes.ok,
  };
}

Resources

• Linktree Developer Docs
• Linktree Status Page
• Linktree API Changelog

Next Steps

See linktree-rate-limits.