# Authentication

URL: https://docs.sigment.ai/authentication

How agents sign in to the Sigment MCP server, and how you approve and revoke them.

Every request to `https://api.sigment.ai/mcp` needs `Authorization: Bearer <token>`. Two kinds of token are accepted:

| Token | Prefix | How you get it | Approval |
|---|---|---|---|
| OAuth access token | `oat_` | The client (Claude, ChatGPT, Cursor, Claude Code) signs you in through the browser | You approve the agent in **Settings → AI agents** |
| API key | `ak_` | **Settings → AI agents → API keys** | Approved automatically |

Session tokens from the Sigment web app are **not** accepted at `/mcp`. Organization-owned keys aren't accepted either: a key must belong to a user.

## OAuth discovery

Sigment follows the MCP authorization spec, so clients configure themselves. A request without a token gets `401` with a `WWW-Authenticate` header pointing at the protected resource metadata:

```bash
curl https://api.sigment.ai/.well-known/oauth-protected-resource/mcp
```

```json
{
  "resource": "https://api.sigment.ai/mcp",
  "authorization_servers": ["https://clerk.sigment.ai"],
  "bearer_methods_supported": ["header"]
}
```

The authorization server supports dynamic client registration, so there's no client ID to configure.

## Approving and revoking agents

The first call from a new OAuth client registers it in **Sigment → Settings → AI agents**, but its tool calls are refused until you approve it. You can revoke an agent or an API key on the same page at any time. A revoked agent gets a message telling the user to re-approve it, and only the account owner can do that.

## Workspaces

Tools act on your workspaces. Every tool takes an optional `workspace_id`; without it, the tool uses your first workspace. `get_account` lists them.

## Why not the REST API?

The REST API is reserved for the Sigment app. It answers `403 "OAuth access tokens and API keys are accepted only at the /mcp endpoint"` to agent credentials. The MCP tools are bounded, rate-limited and budget-capped, which is what makes it safe to hand them to an agent.

---

# Sigment for AI agents

URL: https://docs.sigment.ai/

Sigment finds and vets social creators by their real audiences. Claude and other AI agents use it through one MCP server.

Sigment measures who actually engages with Instagram, YouTube and TikTok creators, and how much of that audience the creators share. Any agent that speaks the [Model Context Protocol](https://modelcontextprotocol.io) can drive it: discover creators for a topic, analyze their shared ("core") audience, optimize a selection and save a shareable shortlist.

```txt title="MCP server URL"
https://api.sigment.ai/mcp
```

<Cards>
  <Card title="Quickstart" href="/quickstart" description="Connect Claude and build your first shortlist in two minutes." />
  <Card title="Claude Code" href="/connect/claude-code" description="One command: claude mcp add." />
  <Card title="Tools" href="/tools/account-credits" description="The 24 tools, their inputs and limits." />
  <Card title="Credits" href="/guides/credits-and-max-credits" description="What costs credits and how to cap an agent's spend." />
</Cards>

## How an agent uses Sigment

1. `get_account`: check the workspace, the credit balance and today's agent budget.
2. `discover_creators` (new creators for a topic) or `search_creators` (known handles).
3. `wait_for_job`, then `get_discovery`.
4. `analyze_creators`, then `wait_for_job` and `get_analysis_result`.
5. `create_creator_list` / `set_creator_list`, then `share_creator_list` when the user asks for a link.

Paid tools spend the workspace's credits: discovery costs 20, an analysis 15, and a re-analysis 5. Agents call `quote_cost` first and pass `max_credits`, so a call never spends more than the user allowed.

## What is and isn't available

- **MCP** is the supported way to use Sigment programmatically. Sign in with OAuth (Claude, ChatGPT, Cursor) or use an API key for headless agents.
- **The REST API** behind the app isn't public. It refuses OAuth tokens and API keys with `403`, so build on the MCP tools instead.

<Callout title="Docs for agents">
  Every page is also available as Markdown: add `.mdx` to its URL. [`/llms.txt`](https://docs.sigment.ai/llms.txt) indexes them, and [`/llms-full.txt`](https://docs.sigment.ai/llms-full.txt) has everything in one file. To let Claude Code read these docs as tools, add the docs MCP server: `claude mcp add --transport http sigment-docs https://docs.sigment.ai/mcp`.
</Callout>

---

# Prompts

URL: https://docs.sigment.ai/prompts

Ready-made workflows the Sigment MCP server ships to your AI client.

MCP prompts appear in your client as commands. In Claude Code, type `/mcp__sigment__build_shortlist`; in claude.ai, pick them from the Sigment connector in the **+** menu. Each one expands into step-by-step instructions that use the tools correctly, including the budget.

| Prompt | What it does | Arguments |
|---|---|---|
| `build_shortlist` | Discovers creators for a brief, analyzes the best candidates, proposes a set and saves a shareable list after you confirm. | `brief`, `platform` (default `instagram`), `max_credits` (default 40) |
| `hit_audience_targets` | Loops discovery → analysis → `optimize_selection` until a set reaches a core % and core reach target, or the budget runs out. Instagram only. | `brief`, `min_core_pct` (7), `min_core_reach` (100000), `max_credits` (100), `max_iterations` (5) |
| `vet_creators` | Measures which creators in a list share an audience and which are redundant, then recommends a subset. | `creators` (handles or a list name), `platform` |
| `reach_plan` | Plans the cheapest mix of an analysis's creators that reaches the most unique core audience within a budget. | `analysis` (name or id), `budget_usd` |

`max_credits` in a prompt is a total budget for the whole workflow. Within it, the agent proceeds without asking at each step.

---

# Quickstart

URL: https://docs.sigment.ai/quickstart

Connect Claude to Sigment and build a creator shortlist in two minutes.

You need a Sigment account with credits ([sign up](https://platform.sigment.ai/sign-up)) and Claude on a plan that supports custom connectors.

## 1. Add the connector

In [claude.ai](https://claude.ai), open **Settings → Connectors**, click **Add custom connector**, and paste:

```txt
https://api.sigment.ai/mcp
```

## 2. Sign in and approve

Claude opens a Sigment sign-in window. Sign in with your Sigment account, then open **Sigment → Settings → AI agents** and approve the new agent. Until you approve it, every tool call answers with a message asking you to.

## 3. Ask for a shortlist

Start a new chat with the Sigment connector enabled and give it a brief and a budget:

```txt
Build me a shortlist of Instagram creators for vegan fitness moms in the US.
Spend at most 60 credits.
```

Claude will check your balance (`get_account`), quote the cost (`quote_cost`), run a discovery and an analysis, and save the best set as a creator list. Paid and public-link tools are marked as destructive, so Claude asks you to allow them unless you chose to always allow them.

<Callout title="Use the built-in prompts">
  The connector also ships prompts such as `build_shortlist` and `hit_audience_targets`, which spell out the whole workflow. See [Prompts](https://docs.sigment.ai/prompts).
</Callout>

## Next steps

- [Claude Code](https://docs.sigment.ai/connect/claude-code) or [Claude Desktop](https://docs.sigment.ai/connect/claude-desktop)
- [Credits and `max_credits`](https://docs.sigment.ai/guides/credits-and-max-credits)
- [Tool reference](https://docs.sigment.ai/tools/account-credits)

---

# Metrics

URL: https://docs.sigment.ai/concepts/metrics

What Sigment measures — audience size, core audience, reach and cost.

Sigment scrapes who engages with each creator's recent content and compares those people across creators. Every number is measured on that sample, not estimated from outside population data.

## Audience

| Metric | Meaning |
|---|---|
| **Unique audience sample** | Distinct people found engaging with the creators |
| **Frequency** | Engagements per person in the sample |
| **Core audience** | People who engage with **2 or more** of the creators (the core threshold, default 2) |
| **Core audience %** | Core audience sample ÷ unique audience sample |
| **Estimated audience size** | People these creators reach: sum of median impressions ÷ frequency. In `get_analysis_result` it's `overview.estimated_audience_size` |
| **Estimated core audience size (core reach)** | Estimated audience size × core audience %. In `get_analysis_result` it's `overview.estimated_core_audience_size` |

When a user asks "how big is the audience", answer with these two numbers.

## Per creator

| Metric | Meaning |
|---|---|
| **Median views** | Median impressions of the creator's content, ignoring zeros |
| **Reach** | Median views ÷ frequency |
| **Core reach** | The creator's share of the core audience size |
| **Cost per post** | Defaults to cost per view × median views; can be overridden |
| **Effective CPV** | Cost per post ÷ median views |

## Demographics

Sigment has **no per-follower gender, age or location**. `get_creator` returns audience demographics only for creators who connected their account. Treat words like "men", "US" or "18+" in a brief as rules for choosing creators (bio, location, language, content), and never block on missing demographics.

---

# API keys and raw MCP

URL: https://docs.sigment.ai/connect/api-keys

Call the Sigment MCP server from scripts and headless agents with an API key.

Create a key in **Sigment → Settings → AI agents → API keys**. Keys start with `ak_`, are approved automatically, and can be revoked on the same page. Send the key on every request:

```http
Authorization: Bearer ak_...
```

## Use an MCP client library

The easiest route is an official MCP SDK with the Streamable HTTP transport. For example, in Python (`pip install "mcp>=2"`):

```python
import asyncio, httpx2
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

async def main():
    http = httpx2.AsyncClient(headers={"Authorization": "Bearer ak_..."}, timeout=60)
    async with http, streamable_http_client("https://api.sigment.ai/mcp", http_client=http) as (read, write, *_):
        async with ClientSession(read, write) as session:
            await session.initialize()
            print(await session.call_tool("get_account", {}))

asyncio.run(main())
```

## Raw JSON-RPC

The server is **stateless**: every request is a plain `POST` that returns JSON, so no session ID or SSE stream is needed. `GET /mcp` returns `405`. Send both `Accept` types:

```bash
curl -s https://api.sigment.ai/mcp \
  -H "Authorization: Bearer $SIGMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Call a tool:

```bash
curl -s https://api.sigment.ai/mcp \
  -H "Authorization: Bearer $SIGMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"quote_cost","arguments":{"action":"discovery"}}}'
```

Tool errors come back as a normal result with `"isError": true` and a message that tells the agent what to do next. See [Errors](https://docs.sigment.ai/guides/errors).

---

# ChatGPT

URL: https://docs.sigment.ai/connect/chatgpt

Connect Sigment to ChatGPT in developer mode.

1. In ChatGPT, open **Settings → Apps & Connectors** and turn on **Developer mode**.
2. Create a connector and paste `https://api.sigment.ai/mcp`.
3. Choose **OAuth** as the authentication and sign in with your Sigment account.
4. Approve the agent in **Sigment → Settings → AI agents**.

---

# Claude Code

URL: https://docs.sigment.ai/connect/claude-code

Add the Sigment MCP server to Claude Code with one command.

## With your Sigment account (OAuth)

```bash
claude mcp add --transport http sigment https://api.sigment.ai/mcp
```

Then run `/mcp` inside Claude Code, select **sigment** and choose **Authenticate**. A browser opens for the Sigment sign-in. After that, approve the agent in **Sigment → Settings → AI agents**.

Add `--scope user` to make it available in every project, or `--scope project` to share it with your team through `.mcp.json`:

```json title=".mcp.json"
{
  "mcpServers": {
    "sigment": { "type": "http", "url": "https://api.sigment.ai/mcp" }
  }
}
```

## With an API key (headless)

For CI or other places that can't open a browser, create an API key in **Sigment → Settings → AI agents** and pass it as a header:

```bash
claude mcp add --transport http sigment https://api.sigment.ai/mcp \
  --header "Authorization: Bearer $SIGMENT_API_KEY"
```

API keys are approved automatically. Anyone holding one can spend your workspace's credits, so keep it in a secret store, not in `.mcp.json`.

## Also add the docs

The docs have their own small MCP server with `search_docs` and `get_doc_page`, so Claude Code can look things up while it works:

```bash
claude mcp add --transport http sigment-docs https://docs.sigment.ai/mcp
```

## Check it works

```txt
> Use sigment to show my credit balance, then quote a discovery for "home espresso".
```

Claude Code should call `get_account` and then `quote_cost`.

---

# Claude Desktop

URL: https://docs.sigment.ai/connect/claude-desktop

Use Sigment in the Claude desktop app.

Claude Desktop shares connectors with claude.ai. Add Sigment once, as described in [Claude (claude.ai)](https://docs.sigment.ai/connect/claude), and it appears in the desktop app too. You can also add it from **Settings → Connectors → Add custom connector** in the app.

Don't add Sigment to `claude_desktop_config.json`: that file is for local (stdio) servers, and Sigment is a remote server.

After connecting, approve the agent in **Sigment → Settings → AI agents**.

---

# Claude (claude.ai)

URL: https://docs.sigment.ai/connect/claude

Add Sigment as a custom connector in claude.ai.

Custom connectors are available on Claude's paid plans. On Team and Enterprise plans, an owner may need to add the connector for the organization first.

1. Open **Settings → Connectors** and click **Add custom connector**.
2. Name it `Sigment` and paste the URL: `https://api.sigment.ai/mcp`. Leave the OAuth client fields empty: Claude registers itself.
3. Click **Connect** and sign in with your Sigment account.
4. In Sigment, open **Settings → AI agents** and approve the agent.
5. In a chat, enable the connector from the tools menu.

The connector also works in the Claude mobile apps once it's added on the web.

## Troubleshooting

- **"… is not approved to use this Sigment account yet"**: approve the agent in **Settings → AI agents**, then retry.
- **"Access … was revoked by the user"**: only you can re-approve it, in the same page.
- **The sign-in window loops**: sign out of Sigment in the browser and connect again.

---

# Cursor

URL: https://docs.sigment.ai/connect/cursor

Add Sigment to Cursor's MCP settings.

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json title="mcp.json"
{
  "mcpServers": {
    "sigment": { "url": "https://api.sigment.ai/mcp" }
  }
}
```

Cursor shows a **Needs login** button next to the server. Click it, sign in with Sigment, and approve the agent in **Sigment → Settings → AI agents**.

To use an [API key](https://docs.sigment.ai/connect/api-keys) instead, add a header:

```json
{
  "mcpServers": {
    "sigment": {
      "url": "https://api.sigment.ai/mcp",
      "headers": { "Authorization": "Bearer ${env:SIGMENT_API_KEY}" }
    }
  }
}
```

---

# Hitting audience targets

URL: https://docs.sigment.ai/guides/audience-targets

Iterate analyze → optimize until a creator set reaches a core % and core reach target.

When a brief has targets, such as "at least 7% core audience and 100,000 core reach", use `optimize_selection` (Instagram only, 5 credits). It searches an analysis's already-scraped data for the best subset, so it doesn't scrape again.

1. `create_creator_list` for the brief, so the run always ends with a list.
2. `analyze_creators` with 15–30 candidates, then `wait_for_job`.
3. `optimize_selection(analysis_id, min_core_pct, min_core_reach, max_credits)`. It returns:
   - `current` and `best` sets, and whether the targets are met;
   - the gaps to the targets;
   - `drag_creators`: removing them raises core %;
   - `suggested_additions`: already-scraped creators whose audience overlaps this core.
4. `set_creator_list` with `best` and a description holding its core % and core reach.
5. If the targets aren't met, drop the drag creators, add the suggestions (or `discover_creators` on a narrower subtopic when reach is short) and go back to step 2.

Stop when the targets are met, the budget is spent, or two rounds bring no improvement. The [`hit_audience_targets`](https://docs.sigment.ai/prompts) prompt runs this loop for you.

---

# Credits and max_credits

URL: https://docs.sigment.ai/guides/credits-and-max-credits

What costs credits, how agents quote first, and how max_credits caps every paid call.

Paid tools spend the workspace's credits. Reads, lists, searches and sharing are free.

| Action | Tool | Cost |
|---|---|---|
| Discovery (per topic) | `discover_creators` | 20, or free if the same topic ran in the last 24 hours |
| New analysis | `analyze_creators` | 15 |
| Re-analysis (same creators within 30 days) | `analyze_creators`, `run_analysis` | 5 |
| Optimization | `optimize_selection` | 5 |

## Quote, then cap

1. Call `quote_cost` with the action. It returns the price and whether the balance covers it.
2. Pass `max_credits` to the paid tool. If the price is above it, the tool **doesn't start** and charges nothing:

```txt
Not started: this costs 20 credits, above max_credits=10. Ask the user whether to spend 20 credits; do not raise max_credits …
```

Agents should ask the user rather than retry with a higher `max_credits`.

## Charges and refunds

- Paid results include `credits` with what was charged and the remaining balance.
- An analysis is charged when its scrape finishes. Failed paid work is refunded.
- `get_credit_history` lists charges, refunds and top-ups.

## Out of credits

Agents can't pay. When the balance is short, the tool says so and the agent should call `get_topup_link` and give the link to the user.

## Daily agent cap

Agents can spend at most **200 credits per workspace per UTC day**, whatever the balance. `get_account` shows today's agent spend. Past the cap, paid tools refuse until midnight UTC; the user can keep working in the Sigment app.

---

# Errors

URL: https://docs.sigment.ai/guides/errors

What each error means and what the agent should do.

Tool failures come back as a tool result with `isError: true` and a message written for the agent. The message says what to do next.

| Message starts with | Cause | What to do |
|---|---|---|
| `"…" is not approved to use this Sigment account yet` | New OAuth client | The user approves it in **Settings → AI agents** |
| `Access for "…" was revoked by the user` | The user revoked the agent | Only the user can re-approve it |
| `Not started: this costs N credits, above max_credits=M` | Price above the cap | Ask the user; don't raise `max_credits` yourself |
| `Insufficient credits` | Balance too low | Stop and give the user `get_topup_link` |
| `Daily agent spend cap reached` | 200 credits spent today | Continue in the app or wait until midnight UTC |
| `Plan limit` | The plan doesn't allow it | The user upgrades in the app |
| `Already in progress` | Duplicate job | Poll the existing job |
| `Too many active jobs` | Workspace job limit | `wait_for_job` on the running jobs, then retry |
| `Sigment is busy` | Platform at capacity | Retry in a few minutes |
| `Not found, or this account has no access to it` | Wrong id or workspace | Check the id with the list tools |
| `Sigment could not confirm this session right now` | Transient auth check | Retry shortly |

## HTTP-level errors

| Status | Meaning |
|---|---|
| `401` + `WWW-Authenticate` | Missing or invalid token: start the OAuth flow, or check the API key |
| `405` | `GET /mcp`: the server is POST-only |
| `429` + `Retry-After` | Too many requests in flight: wait the given seconds |

---

# Jobs and polling

URL: https://docs.sigment.ai/guides/jobs-and-polling

How long work runs, how to wait for it, and what never to do.

Discoveries take a few minutes, and analyses several minutes, longer when the scraper is busy. Paid tools return a `job_id` immediately.

```txt
discover_creators(...)        → { job_id: "discovery:…", poll_after_seconds: 30 }
wait_for_job(job_id)          → { status: "running", stage: "scraping" }   # after up to 25 s
wait_for_job(job_id)          → { status: "completed" }
get_discovery(discovery_id)   → results
```

- `wait_for_job` blocks for at most **25 seconds** (larger `timeout_seconds` values are capped). If the job is still running, call it again.
- `stage: "queued"` means the scraper is at capacity. The job **starts by itself**: keep waiting.
- **Never resubmit a running or queued job.** A duplicate is refused with "Already in progress … Poll the existing job instead".
- `failed` jobs are refunded. Read the message before retrying.
- To resume later, `list_discoveries` and `list_analyses` return earlier work.

---

# Limits

URL: https://docs.sigment.ai/guides/limits

Rate limits and concurrency caps for agents.

These limits apply to agent credentials (OAuth tokens and API keys), not to people using the Sigment app.

| Limit | Value | When exceeded |
|---|---|---|
| Tool calls | 120 per user per minute | Tool error, retry after a minute |
| `search_creators` | 60 per user per hour | Tool error |
| Requests in flight | A few per token and 8 tool calls per user | `429` with `Retry-After` |
| Active discoveries | 3 per workspace | "Too many active jobs": wait for them |
| Active analyses | 5 per workspace | "Too many active jobs": wait for them |
| Agent spend | 200 credits per workspace per UTC day | "Daily agent spend cap reached" |
| Platform busy | Agent work pauses briefly when many jobs are running | "Sigment is busy": retry in a few minutes |

Input bounds keep every call small: up to 50 handles per analysis, 100 usernames per list update, 20 creators per discovery subtopic and `max_credits` ≤ 1000.

Call tools one at a time and let `wait_for_job` do the waiting. Parallel polling only uses up the limits faster.

---

# Account and credits

URL: https://docs.sigment.ai/tools/account-credits

Check the workspace, balance and prices, and send the user a top-up link.

Start every session with `get_account`, and call `quote_cost` before any paid tool.

### get_account

Workspaces, plan, credit balance, prices and today's agent spend. Call this first.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `workspace_id` | `string` | no |  | 1–100 chars |

### quote_cost

Price an action before doing it. For analysis pass the creator handles (new analysis) or analysis_id (re-run): re-analyses of creators seen in the last 30 days cost 5 instead of 15.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `action` | `"discovery" \| "analysis"` | yes |  |  |
| `platform` | `"instagram" \| "youtube" \| "tiktok"` | no | "instagram" |  |
| `handles` | `string[]` | no |  | 1–50 items |
| `analysis_id` | `string` | no |  | 1–100 chars |
| `workspace_id` | `string` | no |  | 1–100 chars |

### get_credit_history

Recent credit charges, refunds and top-ups for the workspace.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `limit` | `integer` | no | 20 | 1–100 |
| `workspace_id` | `string` | no |  | 1–100 chars |

### get_topup_link

A Stripe checkout link for the HUMAN user to buy credits. Agents cannot pay: give the user the URL.

Kind: write

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `package_id` | `"starter" \| "growth" \| "scale"` | no | "starter" |  |
| `workspace_id` | `string` | no |  | 1–100 chars |

---

# Analysis

URL: https://docs.sigment.ai/tools/analysis

Measure a creator set's real and shared audience, optimize it, and share the result.

`analyze_creators` scrapes up to 50 creators and measures their audience (15 credits, or 5 for creators analyzed in the last 30 days). It returns a `job_id`. When the job completes, `get_analysis_result` has the overview, campaign metrics, top creators and the interest graph. See [Metrics](https://docs.sigment.ai/concepts/metrics) for what the numbers mean.

### analyze_creators

Scrape up to 50 creators, then measure their real (shared/core) audience and campaign economics. Costs 15 credits (5 if these creators were analyzed in the last 30 days), charged when the scrape finishes; refunded if it fails. Takes minutes: returns a job_id for wait_for_job. When the scraper is at capacity the job queues (stage "queued") and starts by itself: keep waiting, do not resubmit.

Kind: asks before running

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `platform` | `"instagram" \| "youtube" \| "tiktok"` | yes |  |  |
| `handles` | `string[]` | yes |  | 1–50 items |
| `max_credits` | `integer` | yes |  | 0–1000 |
| `workspace_id` | `string` | no |  | 1–100 chars |

### run_analysis

Re-run an existing analysis on fresh data. Usually 5 credits (15 if it never completed). Returns a job_id for wait_for_job.

Kind: asks before running

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `platform` | `"instagram" \| "youtube" \| "tiktok"` | yes |  |  |
| `analysis_id` | `string` | yes |  | 1–100 chars |
| `max_credits` | `integer` | yes |  | 0–1000 |

### get_analysis_result

Audience analysis results: overview, campaign metrics, top creators by core audience, recommended selection, coverage mixes and the interest graph (strongest audience overlaps + clusters). "How big is the audience" = overview.estimated_audience_size (people these creators reach) and overview.estimated_core_audience_size (core reach: people engaging with 2+ of them), measured by Sigment. Pass min_core_pct / min_core_reach to get targets_met and the gaps. Defaults to the latest result.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `platform` | `"instagram" \| "youtube" \| "tiktok"` | yes |  |  |
| `analysis_id` | `string` | yes |  | 1–100 chars |
| `snapshot_id` | `string` | no |  | 1–100 chars |
| `top_n` | `integer` | no | 10 | 1–50 |
| `min_core_pct` | `number` | no |  | 0–100 |
| `min_core_reach` | `integer` | no |  | ≥ 0 |

### optimize_selection

Search an Instagram analysis's creators for the subset that reaches min_core_pct (core audience %) and min_core_reach (estimated core audience size), from already-scraped likes: no new scrape. Costs 5. Returns current and best sets (met or the closest), the gaps, drag_creators (removing them raises core %) and suggested_additions (already-scraped creators whose likers overlap this core audience). Iterate: re-analyze best + additions (analyze_creators), optimize again, until met.

Kind: asks before running

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `analysis_id` | `string` | yes |  | 1–100 chars |
| `min_core_pct` | `number` | yes |  | 0–100 |
| `min_core_reach` | `integer` | yes |  | ≥ 0 |
| `max_credits` | `integer` | yes |  | 0–1000 |

### list_analyses

Saved analyses in the workspace for one platform.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `platform` | `"instagram" \| "youtube" \| "tiktok"` | yes |  |  |
| `workspace_id` | `string` | no |  | 1–100 chars |

### share_analysis

PUBLIC link to an Instagram analysis result: anyone with the URL can view it. Only share when the user asked to. Reuses the result's active link if there is one, else creates one expiring in 30 days. Revoke with revoke_share_link(link_id=...).

Kind: asks before running

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `analysis_id` | `string` | yes |  | 1–100 chars |
| `snapshot_id` | `string` | no |  | 1–100 chars |

---

# Creator lists

URL: https://docs.sigment.ai/tools/creator-lists

Save shortlists, keep them on the current best set, and share them.

A creator list holds creators from one platform. For a brief, create the list first and keep it on the current best set with `set_creator_list`, so every run ends with a list the user can open in Sigment.

### list_creator_lists

The workspace's creator lists (shortlists).

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `workspace_id` | `string` | no |  | 1–100 chars |

### get_creator_list

A creator list with its members. Pass `handles` to analyze_creators (up to 50 per analysis) to vet it.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `list_id` | `string` | yes |  | 1–100 chars |

### create_creator_list

Create an empty creator list (one platform per list). For a creator brief, create it first and keep it filled with the current best set (set_creator_list), so every run ends with a list.

Kind: write

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `name` | `string` | yes |  | 1–255 chars |
| `platform` | `"instagram" \| "youtube" \| "tiktok"` | no | "instagram" |  |
| `description` | `string` | no |  | ≤ 2000 chars |
| `workspace_id` | `string` | no |  | 1–100 chars |

### add_to_creator_list

Add creators (handles on the list's platform) to a list. Re-adding is a no-op.

Kind: write

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `list_id` | `string` | yes |  | 1–100 chars |
| `usernames` | `string[]` | yes |  | 1–100 items |

### set_creator_list

Make a list hold exactly these creators: adds the missing, removes the rest, and optionally sets the description (e.g. the set's core % and core reach).

Kind: write

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `list_id` | `string` | yes |  | 1–100 chars |
| `usernames` | `string[]` | yes |  | 1–100 items |
| `description` | `string` | no |  | ≤ 2000 chars |

### share_creator_list

PUBLIC link to a creator list: anyone with the URL can view it, live. Only share when the user asked to. Returns the list's existing active link if there is one. Revoke with revoke_share_link(list_id=...).

Kind: asks before running

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `list_id` | `string` | yes |  | 1–100 chars |

### revoke_share_link

Turn off a public link: link_id from share_analysis (one analysis link), or list_id to revoke every public link of that creator list. Anyone holding the URL loses access.

Kind: asks before running

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `link_id` | `string` | no |  | 1–100 chars |
| `list_id` | `string` | no |  | 1–100 chars |

---

# Discovery

URL: https://docs.sigment.ai/tools/discovery

Find new creators for a topic, or look up creators you already know.

Use `search_creators` for known handles or names (free), and `discover_creators` for new creators on a topic (20 credits). A discovery returns a `job_id`: wait for it with [`wait_for_job`](https://docs.sigment.ai/tools/jobs), then read it with `get_discovery`.

### search_creators

Look up creators by handle or name across Instagram and YouTube (free, 60 per hour). For finding NEW creators by topic use discover_creators.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `query` | `string` | yes |  | 2–200 chars |
| `limit` | `integer` | no | 5 | 1–10 |

### get_creator

Creator profile with audience demographics (age, gender, geo) where the creator connected their account. creator_id: Instagram handle or sigment_creator_id; YouTube/TikTok: the `id` from search.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `platform` | `"instagram" \| "youtube" \| "tiktok"` | yes |  |  |
| `creator_id` | `string` | yes |  | 1–100 chars |

### discover_creators

Find new creators for a topic (e.g. 'vegan fitness moms'). Costs 20 credits (free if the same topic ran in the last 24h). Returns a job_id: wait_for_job, then get_discovery.

Kind: asks before running

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `topic` | `string` | yes |  | 2–200 chars |
| `max_credits` | `integer` | yes |  | 0–1000 |
| `platforms` | `("instagram" \| "youtube" \| "tiktok")[]` | no | ["instagram"] | 1–3 items |
| `min_followers` | `integer` | no | 2000 | ≥ 0 |
| `per_subtopic_limit` | `integer` | no | 10 | 1–20 |
| `workspace_id` | `string` | no |  | 1–100 chars |

### list_discoveries

Past discovery searches (newest first) — resume earlier work from here.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `limit` | `integer` | no | 10 | 1–50 |

### get_discovery

Creators found by a discovery, grouped by subtopic, plus the strongest audience overlaps. Pass `handles` to get the overlaps involving those creators instead of the global top 15. For the full interest graph of a creator set, analyze_creators it and read get_analysis_result.interest_graph.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `discovery_id` | `string` | yes |  | 1–100 chars |
| `max_per_group` | `integer` | no | 10 | 1–20 |
| `handles` | `string[]` | no |  | ≤ 50 items |

---

# Jobs

URL: https://docs.sigment.ai/tools/jobs

Wait for discoveries and analyses to finish.

Paid work runs in the background. `discover_creators`, `analyze_creators` and `run_analysis` return a `job_id`, which is an opaque handle such as `discovery:…`, `snapshot:…/…` or `pipeline:instagram:…`. Pass it unchanged to these tools. A job's `status` is `running`, `completed` or `failed`, and `stage` shows `queued`, `scraping` or `analyzing`. See [Jobs and polling](https://docs.sigment.ai/guides/jobs-and-polling).

### wait_for_job

Block until the job finishes or timeout (max 25s), then return its status. If still running, call again — discoveries take a few minutes, analyses several minutes, longer when queued.

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `job_id` | `string` | yes |  | ≤ 250 chars |
| `timeout_seconds` | `integer` | no | 25 | 1–45 |

### get_job

Status of a job_id from discover_creators / analyze_creators / run_analysis: running | completed | failed (failed paid work is refunded).

Kind: read-only

| Parameter | Type | Required | Default | Limits |
|---|---|---|---|---|
| `job_id` | `string` | yes |  | ≤ 250 chars |