Look up a public creator profile

Authenticate from your server

Create a key in the dashboard and keep it in a server environment variable. Set SIGNALSHELF_BASE_URL to the origin of your SignalShelf service. Send the key in the x-api-key header. The key is shown once when created and can be revoked from the dashboard; do not publish it in a browser bundle.

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)

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"}'

Provide a handle and a freshness choice

Use one of the ten platform values below. Supply a public handle; Instagram also accepts profile URLs. Mastodon accepts username@instance. Set mode live explicitly for real data, because omitted mode defaults to demo. Choose freshness live, 1h, 24h (default), or 7d.

Read data and metadata together

The data object includes platform, handle, name, bio, followers, following, posts, avatar, verified, url, provider, and sample. Some metrics are unavailable on a platform and are returned as null; null does not mean zero. The meta object reports event_id, mode, cache, credits_charged, fetched_at, age_seconds, and duration_ms.

Handle failures and limits

Errors include a code and message. Check the HTTP status before using data: invalid input uses 400, missing authentication uses 401, insufficient fresh-lookup credits uses 402, and throttled requests use 429. Provider failures do not charge customer credits. The beta currently limits authenticated HTTP requests to 120 per minute per account, with additional IP and authentication limits. Treat limits as protective caps rather than a throughput guarantee.

Look up a shortlist

POST /api/v1/batch accepts an items array containing one to ten lookup objects. All items are validated before processing. The response contains a result for each item and total credits charged; inspect each result because one lookup can fail while another succeeds. Use the dashboard to save selected creators and export a CSV.

Response fields and unavailable metrics

Every platform returns the same core fields: id, name, bio, followers, following, posts, verified, avatar, links, website, location and created_at. Platform-specific data (for example YouTube total views, Twitch live status, LinkedIn industry) is returned in data.details.

Fields a platform does not expose are null, or an empty array for links. SignalShelf never estimates or invents a metric. Each platform page lists every field.

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.

Instagram reference path

For clients using the Scrape Creators path, GET /v1/instagram/profile?handle=... is available. It uses the same public lookup and cache, and returns only public fields SignalShelf can verify. It does not reproduce every upstream field. The route is production-blocked pending source authorization.