Overview
An automated tracking pipeline has three stages: configure prompts via the API, fetch tracking results after runs complete, and optionally receive webhook notifications. Tracking runs are triggered through the Linksii application UI or the daily cron job — not through the public API.
Prompts
Create prompts via the API — questions that Linksii sends to AI platforms on each run
Fetch Results
Use GET /api/v1/tracking to retrieve results after runs complete
Webhooks
Receive a POST to your server when a run completes — no polling needed
Tracking runs are triggered from the Linksii UI (Tracking page) or automatically via the daily cron job. The public API is used to manage prompts and retrieve results, not to trigger runs directly.
1. Set Up Prompts
Prompts are the questions Linksii sends to AI platforms. Good prompts are the questions your customers ask when researching in your category. Create them once and they run on every tracking call.
List existing prompts
curl "https://www.linksii.com/api/v1/prompts?workspace_id=ws_01HXYZ" \ -H "Authorization: Bearer lnk_your_api_key_here"
Create new prompts
Create prompts that reflect how customers search for solutions in your category. Aim for 5–15 prompts covering awareness, consideration, and decision stages.
curl -X POST https://www.linksii.com/api/v1/prompts \
-H "Authorization: Bearer lnk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "ws_01HXYZ",
"text": "What are the best project management tools for remote teams?",
"category": "awareness",
"is_active": true
}'Prompt response
{
"data": {
"id": "prompt_01HABC",
"workspace_id": "ws_01HXYZ",
"text": "What are the best project management tools for remote teams?",
"category": "awareness",
"is_active": true,
"created_at": "2025-06-01T10:00:00Z"
}
}2. Fetch Tracking Results
After a tracking run completes (triggered from the Linksii UI or the daily cron job), use GET /api/v1/tracking to fetch the results for your workspace.
curl "https://www.linksii.com/api/v1/tracking?workspace_id=ws_01HXYZ&limit=10" \
-H "Authorization: Bearer lnk_your_api_key_here" \
| jq '.data[] | {platform, score, mention_count, ran_at}'Response
{
"data": [
{
"run_id": "run_01HPQR",
"workspace_id": "ws_01HXYZ",
"platform": "chatgpt",
"score": 72,
"mention_count": 6,
"prompt_count": 3,
"status": "complete",
"ran_at": "2025-06-01T10:07:12Z"
},
{
"run_id": "run_01HPQR",
"workspace_id": "ws_01HXYZ",
"platform": "claude",
"score": 65,
"mention_count": 4,
"prompt_count": 3,
"status": "complete",
"ran_at": "2025-06-01T10:07:15Z"
}
],
"meta": { "total": 4, "limit": 10, "offset": 0 }
}3. Webhook Notifications
In production, use webhooks instead of polling. Linksii POSTs to your endpoint when a tracking run completes, delivering the full results payload.
Register a webhook endpoint
curl -X POST https://www.linksii.com/api/v1/webhooks \
-H "Authorization: Bearer lnk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "ws_01HXYZ",
"url": "https://your-app.com/webhooks/linksii",
"events": ["tracking.completed"],
"secret": "your_webhook_secret_32chars_min"
}'Handle the incoming webhook
Linksii signs each webhook with HMAC-SHA256 using your secret. Always verify the signature before processing.
# Webhook payload example (sent by Linksii to your endpoint)
# POST https://your-app.com/webhooks/linksii
# Headers:
# X-Linksii-Signature: sha256=abc123...
# Content-Type: application/json
{
"event": "tracking.completed",
"run_id": "run_01HPQR",
"workspace_id": "ws_01HXYZ",
"results": [
{ "platform": "chatgpt", "score": 72, "mention_count": 6 },
{ "platform": "claude", "score": 65, "mention_count": 4 },
{ "platform": "gemini", "score": 58, "mention_count": 3 },
{ "platform": "perplexity", "score": 70, "mention_count": 5 }
],
"occurred_at": "2025-06-01T10:07:30Z"
}Always return a 2xx response quickly (<5s). Do heavy processing in a background job — Linksii retries failed webhooks up to 3 times with exponential backoff.
Error Handling
| Code | Cause & Fix |
|---|---|
| 400 | Missing workspace_id parameter. Include workspace_id as a query parameter on GET /api/v1/tracking. |
| 401 | Invalid or expired API key. Generate a new key in Settings > API Keys. |
| 400 | Webhook URL not reachable. Linksii validates that the URL responds with 2xx during registration. |