# 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 |