Skip to main content

SocialProfiler API skill for AI agents

The SocialProfiler API skill is a single Markdown file that teaches an AI agent (Claude Code, Claude Agent SDK, or any agent that loads SKILL.md files) how to use this API safely.

Download: SKILL.md

https://dashboard.socialprofiler.com/docs/agent-skills/socialprofiler-api/SKILL.md

What the skill covers​

  • Sign-in with token: true to get a JWT, when POST /auth/token/refresh works and when it is refused, and why an agent cannot sign up (reCAPTCHA).
  • The report lifecycle with People search: create a report with fields (a name, @handle or phone plus facts), run search rounds, pick the accounts that are the person (skipping ones with a blocking badReason), confirm, then wait via GET /check/{reportId} or SSE (ping/follows/summary/ confirm events) and read the report. The deprecated classic per-network flow is mentioned only so that an agent does not use it.
  • Credits: creating a report (POST /create) checks the credit, so 402 there means no report credits are left. Confirming does not spend one: the credit is spent the first time the owner reads the finished report. What 403/401/409/422 mean at each step, including a repeat confirm (409), and why confirm needs a real signed-in account (not a guest session).
  • Readiness: what ready and generated mean in GET /check/{reportId}, and that the AI summary is ready when the SSE summary event reports done. Times in responses are in seconds.
  • Soft errors: sign-up, recovery and Google calls that return HTTP 200 with a fieldError in the body (sign-in bad credentials are a 401).
  • Guardrails: keep credentials out of logs, only create/confirm a report the user asked for, let the user pick the accounts before confirming.

Install​

Claude Code​

Download the file into a skills folder, either for your user or for one project:

# user-wide
mkdir -p ~/.claude/skills/socialprofiler-api
curl -fsSL https://dashboard.socialprofiler.com/docs/agent-skills/socialprofiler-api/SKILL.md \
-o ~/.claude/skills/socialprofiler-api/SKILL.md

# or per project
mkdir -p .claude/skills/socialprofiler-api
curl -fsSL https://dashboard.socialprofiler.com/docs/agent-skills/socialprofiler-api/SKILL.md \
-o .claude/skills/socialprofiler-api/SKILL.md

Restart the session. The agent loads the skill when a task mentions SocialProfiler or a profile analysis report.

Other agents​

Put the file's content in the agent's system prompt or tool instructions. It is plain Markdown with a short YAML header (name, description).

Credentials​

The skill expects the account email and password in environment variables:

export SP_EMAIL="you@example.com"
export SP_PASSWORD="..."

Use a dedicated account for agent work, so its report credits and history are separate from your own.

Keeping it current​

The skill describes the same API as the API Reference. If a call in the skill and the reference disagree, the reference is correct. Please tell support@socialprofiler.com.