SignalYour first profile lookup
Create a key, fetch a public profile, and inspect its freshness and credit cost using cURL, JavaScript, or Python.
1. Create your account and API key
Register in the dashboard to receive 1,000 free credits + 5,000 to earn (no card). Open API Keys, create a descriptively named key, and copy its full value immediately. Existing keys are shown by prefix only. API keys have account-level privileges, so keep them on your server.
2. Configure server environment variables
Set SIGNALSHELF_BASE_URL to your service origin, without a trailing slash. For SignalShelf this is https://signalshelf.dev. Set SIGNALSHELF_API_KEY to your generated SignalShelf key using your shell or hosting secret manager. This key is different from the operator’s upstream data-provider key.
3. Request a real public profile
Bluesky public profiles do not require a separate upstream provider key. This example requests real data explicitly with mode live. The default mode is demo if omitted. Set the two environment variables before running an example.
curl "$SIGNALSHELF_BASE_URL/api/v1/profiles" \
-H "Content-Type: application/json" \
-H "x-api-key: $SIGNALSHELF_API_KEY" \
--data '{"platform":"bluesky","handle":"bsky.app","mode":"live","freshness":"24h"}'// Run in a server environment. Never expose the key in client-side code.
const response = await fetch(`${process.env.SIGNALSHELF_BASE_URL}/api/v1/profiles`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.SIGNALSHELF_API_KEY,
},
body: JSON.stringify({"platform":"bluesky","handle":"bsky.app","mode":"live","freshness":"24h"}),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error?.code}: ${result.error?.message}`);
console.log(result);# Server-side Python; install requests if needed.
import os
import requests
response = requests.post(
os.environ['SIGNALSHELF_BASE_URL'] + "/api/v1/profiles",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
json={'platform': 'bluesky', 'handle': 'bsky.app', 'mode': 'live', 'freshness': '24h'},
timeout=45,
)
result = response.json()
response.raise_for_status()
print(result)4. Inspect the response
Check the HTTP status, then read data and meta together. A successful live miss costs one credit. A usable cached result costs zero. Profile values change over time; the following is an illustrative response, not a measurement of the named account.
{
"data": {
"platform": "bluesky",
"handle": "bsky.app",
"name": "Bluesky",
"bio": "Example profile description",
"followers": 123456,
"following": 42,
"posts": 900,
"avatar": null,
"verified": null,
"url": "https://bsky.app/profile/bsky.app",
"provider": "bluesky-public",
"sample": false
},
"meta": {
"event_id": "example-event-id",
"mode": "live",
"cache": "MISS",
"credits_charged": 1,
"fetched_at": "2026-10-19T12:00:00.000Z",
"age_seconds": 0,
"duration_ms": 850
}
}5. Repeat, save, or batch
Repeat with freshness 24h to accept a cached result while it remains eligible. Save the returned meta.event_id through POST /api/saved, or send up to ten lookup objects to POST /api/v1/batch. Follow the caching, saved creator, and batch guides for those workflows.
Troubleshoot your first request
UNAUTHENTICATED means the SignalShelf key is missing, revoked, or invalid. Instagram may fail when the public page is blocked, requires login, or changes its markup. TikTok and YouTube live engines are not implemented. Sample mode is available while live access is being set up. Never share keys in a support screenshot.
Current live engine availability
Public profile live access varies by deployment. Instagram, TikTok, LinkedIn, Pinterest, Snapchat, Twitch, Apple Music, and YouTube live routes are disabled in production pending source-specific authorization or resale review. GitHub, Mastodon, and Bluesky live routes remain subject to source availability. Public-page extraction can fail on rate limits, access restrictions, markup changes or regional blocks. Browser fallback requires the worker to be configured and running. No competitor API or social-account login is used.