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

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.