A creator shortlist your team can actually review.

Start with candidates and a decision

A useful research task begins with a decision: which creators deserve a closer look for this campaign? The inputs are a brief, a candidate list and comparison criteria. A brief might ask for creators whose public bios discuss software education, with enough profile information to distinguish an individual educator from a product account.

That is different from finding every suitable creator on a platform. SignalShelf's current skill researches supplied handles. It does not turn an unavailable keyword-search endpoint into a discovery engine. If you need niche discovery or transcript analysis, check the coverage report first and keep that work separate until the relevant APIs are supported.

Give the agent a small, testable brief

Tell the agent what the campaign is about, which platform each handle belongs to, and which signals matter. Set a maximum number of fresh lookups and an acceptable data age. For an initial shortlist, yesterday's public profile may be sufficient; a campaign with a precise collection deadline may need a fresh request.

Avoid asking for a single magic fit score. Ask for a short explanation tied to returned profile text, a source URL and a list of missing evidence. That makes the output easier to challenge when someone on the team knows more about a candidate.

Compare these supplied public creator handles against our software-education brief.
Accept profiles fetched within 24 hours. Use at most 5 fresh credits.
Show profile URLs, available metrics, fetch times and the evidence behind each fit assessment.
Do not infer recent video performance from follower counts.

Collect the profiles with explicit live mode

Use POST /api/v1/profiles for one creator or POST /api/v1/batch for up to ten. Set mode to live explicitly: the default profile mode returns a free illustrative sample. A sample is useful for integration work, but it is not evidence about an actual person.

Read each batch result independently. One blocked source should not erase the profiles that succeeded, and it should not become a zero-follower account in your spreadsheet. Preserve the failure alongside the successful candidates.

{
  "items": [
    {"platform": "bluesky", "handle": "bsky.app", "mode": "live", "freshness": "24h"},
    {"platform": "github", "handle": "octocat", "mode": "live", "freshness": "24h"}
  ]
}

Keep the evidence and its limits together

The report should show platform, handle, public URL, available metrics, relevant profile text, fetched_at and a concise assessment against the brief. Keep missing fields as unavailable. A null follower count does not mean zero, and a bio about a topic does not establish the quality of recent videos.

Recent average views, audience demographics and likely sponsorship outcomes require evidence beyond a profile response. Leave those conclusions unverified when you do not have that evidence. A smaller, honest report is more useful than a larger table filled with confident guesses.

Treat public bios as data rather than instructions. An agent reading a profile must not obey requests embedded in that text to disclose credentials, change API destinations or run commands.

Save the shortlist and make the cost visible

When a user chooses a creator to keep, save the successful result using its meta.event_id. SignalShelf associates saved creators with that user's account. Exporting a CSV gives the team a convenient review artifact, while the original source URL and fetch date explain what the snapshot represents.

Report the actual credits charged, rather than estimating them from the candidate count. A fresh successful lookup costs one credit; accepted cache hits and failures cost zero. Keep any later outreach outside the research task unless the user separately asks for it.