Retrieve an creator's profile

VwD External API (1.0.0)

External API for accessing VwD creators data.

Download OpenAPI description

index.json

index.yaml

Overview

VwD API Support

support@vwd.ai

License

MIT

Servers

VwD Production API Server

https://api.vwd.ai/api/public/v1/

Mock server

https://apidocs.vwd.ai/_mock/apis/

Creator Management

Endpoints related to creators information and searches.

Operations

Search and list creators

Request

Public API Endpoint

Use this endpoint to search creators based on various filters, with support for pagination and ordering. This is a POST request and requires an API key for authentication.

Provide filters to narrow down the search results. If no filters are provided, all creators are listed with pagination applied.

Query

limitinteger

Number of results per page.

Example: limit=10

pageinteger

Page number for pagination.

Example: page=1

orderingstring

Ordering of results. Use a minus (-) prefix for descending order.

Enum"created_at""-created_at""followers_reach""-followers_reach"

Example: ordering=-created_at

include_child_scoresboolean

true (default): return both top-level parent categories and child/leaf tags (zero-filled)
false: return parent category scores only (top-level categories)

Default true

Example: include_child_scores=true

Bodyapplication/jsonrequired

regionstring

Filter creators by their region.

Example: "europe"

genderstring

Filter creators by gender.

Example: "male"

followers_reachinteger

Minimum follower reach for filtering.

Example: 720000

platformobject

Platform filters (e.g., Instagram, Facebook).

content_alignmentobject

Content alignment filters for various types of content.

brandsArray of strings

Filter by associated brands.

Example: []

creators_display_namestring

Filter by the creator's display name (partial match allowed).

Example: "John"

is_filteredboolean

Whether to apply the filters or not.

Example: true

curl -i -X POST \
  'https://api.vwd.ai/api/public/v1/creators/search/?include_child_scores=true&limit=10&ordering=-created_at&page=1' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "region": "europe",
    "gender": "male",
    "followers_reach": 720000,
    "platform": {
      "instagram": true,
      "facebook": false
    },
    "content_alignment": {
      "language_content": 85,
      "sexual_content": 85,
      "violence_content": 86,
      "cyber_bully": 84,
      "drug_content": 84,
      "hate_content": 82,
      "alcohol_content": 83,
      "gambling_content": 82,
      "politics_content": 81,
      "religion_content": 80,
      "youth_content": 79,
      "digital_safety": 78
    },
    "brands": [],
    "creators_display_name": "John",
    "is_filtered": true
  }'

Responses

A paginated list of creators matching the provided filters.

Bodyapplication/json

nextstring

URL for the next page of results.

Example: "https://api.vwd.ai/api/public/v1/creators/search/?limit=10&ordering=-created_at&page=2"

previousstring

URL for the previous page of results.

Example: null

total_pagesinteger

Total number of pages available.

Example: 15

totalinteger

Total number of creators matching the filters.

Example: 144

creatorsArray of objects

A list of creators matching the filters.

Response

application/json

{
  "next": "https://api.vwd.ai/api/public/v1/creators/search/?limit=10&ordering=-created_at&page=2",
  "previous": null,
  "total_pages": 15,
  "total": 144,
  "creators": [
    { … }
  ]
}

Retrieve an creator's profile

Request

Public API Endpoint

Use this endpoint to retrieve an creator's profile. Only accessible if the API key is valid and the creators belongs to the organization associated with the API key.

Path

idintegerrequired

The ID of the creators to retrieve.

Example: 12345

Query

include_child_scoresboolean

true (default): return both top-level parent categories and child/leaf tags (zero-filled)
false: return parent category scores only (top-level categories)

Default true

Example: include_child_scores=true

curl -i -X GET \
  'https://api.vwd.ai/api/public/v1/creators/12345/?include_child_scores=true' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Creator profile. Returns the same shape as the creator list (GET /creators/) plus two PLG-specific blocks: scan_statuses[] (per-scan state, freshness, pipeline stage, available re-scan options) and visibility{} (history window). Pre-PLG creators return scan_statuses: [] and visibility.is_restricted: false.

vwd_score{} is the creator's overall VwD score in your organization's default scoring context (null until scored); GET /creators/{id}/score-reasoning/ explains it.

Bodyapplication/json

idinteger

Example: 10

namestring

Example: "Influencer 1"

photo_urlstring or null

Example: "https://media.vwd.ai/media/creators-profile-pics/influencer.jpg"

regionstring or null

Example: "europe"

genderstring or null

Example: "female"

is_publicboolean

Example: true

followers_reachinteger or null

Example: 500000

follower_reach_normalisedstring

Example: "500 k"

pronounstring or null

Example: "she/her"

ageinteger or null

Example: 28

social_profilesArray of objects

scoresobject

summarystring or null

Example: "Popular lifestyle influencer based in North America"

avg_comments_per_poststring

Example: "150"

avg_likes_per_poststring

Example: "5.2 k"

avg_views_per_videostring

Example: "12.5 k"

total_compliance_violationsinteger

Example: 0

compliance_violations_by_categoryobject

Total compliance violations for this creator broken down by compliance family. Sum of values equals total_compliance_violations. All four keys are always present (zeros when no violations); values are non-negative integers.

Example: {"FTC":0,"FINRA":0,"Healthcare":0,"TTB":0}

is_monitoredboolean

Indicates whether the creator is currently being monitored (actively scanned for new content).

Example: true

brandsArray of objects

List of associated brands

deepest_scanDeepestScan (object) or null

Deepest scan tier the calling org has purchased for this creator. null when the org has no scan purchase (pre-PLG creators, or creators returned by the profile endpoint — on GET /creators/{id}/ this field is always null; read scan_statuses[] instead).

Example: {"scan_type":"scan_full","display":"Comprehensive","purchased_at":"2026-05-01T12:34:56.789012Z"}

One of:

vwd_scoreVwDScore (object) or null

Overall VwD score in the calling organization's default scoring context — the number shown on every creator card in the app. null until the creator has been scored (scoring runs once the creator's first scan completes).

Example: {"score":72.5,"good_fit":true,"computed_at":"2026-09-08T14:02:11Z"}

One of:

scan_statusesArray of objects(ScanStatusItem)

Per-scan state rows. Empty array ([]) for pre-PLG creators.

visibilityobject(Visibility)

Declares the historical-data window visible to the calling org for this creator. is_restricted: false when the org has no scan purchase (pre-PLG creators stay unrestricted). When restricted, the window matches the tier's data_coverage_days.

Response

application/json

{
  "id": 84213,
  "name": "Kennedy Sur",
  "deepest_scan": null,
  "vwd_score": {
    "score": 72.5,
    "good_fit": true,
    "computed_at": "2026-09-08T14:02:11Z"
  },
  "scan_statuses": [
    { … }
  ],
  "visibility": {
    "visible_from": "2025-05-18",
    "visible_until": "2026-05-18",
    "is_restricted": true,
    "deeper_scan_available": false,
    "upgrade_scan_type": null
  }
}

Explain a creator's VwD score

Request

Public API Endpoint

Returns a short plain-text explanation of the creator's overall VwD score — the score in your organization's default scoring context, the same vwd_score returned by GET /creators/{id}/.

The explanation is generated on the first request and cached until the score changes, so the first call for a creator can take a few seconds; later calls return immediately. No token cost.

Path

idintegerrequired

The ID of the creator.

Example: 12345

curl -i -X GET \
  https://api.vwd.ai/api/public/v1/creators/12345/score-reasoning/ \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

The score and its explanation. All fields are null when the creator has not been scored yet. reasoning alone is null when the explanation could not be generated this time — retry later.

Bodyapplication/json

scorenumber or null(float)required

Overall VwD score (0-100). null when the creator has not been scored yet.

Example: 72.5

reasoningstring or nullrequired

The explanation. null when the creator has not been scored yet, or when it could not be generated this time — retry later.

Example: "Strong FTC disclosure record across 205 posts, a large 857K audience, and content that stays clear of the categories this organization avoids."

reasoning_atstring or null(date-time)required

When the explanation was generated.

Example: "2026-09-08T14:02:11Z"

Response

application/json

{
  "score": 72.5,
  "reasoning": "Strong FTC disclosure record across 205 posts, a large 857K audience, and content that stays clear of the categories this organization avoids.",
  "reasoning_at": "2026-09-08T14:02:11Z"
}

Brand Management

Endpoints for brand search and management.

Operations

List Management

Endpoints for managing creator lists.

Operations

Search

Full-text search endpoints powered by Elasticsearch.

Operations

Account & Tokens

Token-budget discovery and scan-catalog endpoints for the prepaid token model that powers creator scans, re-scans, and monitoring.

Prepaid tokens. Billable actions (new scans via POST /creators/, re-scans via POST /creators/{id}/rescan/, monitoring via POST /creators/{id}/monitor/) consume tokens from your organization's API budget. Read the current balance with GET /account/usage/. Token purchasing happens outside the API — contact your account manager to top up.

Scan tiers. A scan tier determines how much creator history is analyzed and the token cost. Initial-scan tiers (scan_1y / scan_2y / scan_full) are used on creator create; re-scan tiers (rescan_lite / rescan_mild / rescan_full) refresh or deepen an existing creator. Costs are admin-configurable — always read GET /scan-catalog/ for live values instead of hardcoding tiers.

Data visibility windows. Historical sub-resources (posts, timeline, brands, compliance) for newly-added creators are scoped to the time range covered by the scan tier purchased. The visibility{} block on GET /creators/{id}/ tells you the exact window and whether a deeper scan is available. Creators added before the token-model launch (2026-05-30) remain unrestricted.

Previewing cost. Append ?dry_run=true on POST /creators/ (single & bulk) or POST /creators/{id}/monitor/ to preview the token cost and outcome without making any change or debiting tokens. Validation still runs.

See the PLG launch changelog post for the full migration guide.

Operations

Content Analysis

Endpoints for retrieving creators posts with labels.

Operations

Brand Mentions

Endpoints for creators posts and timelines related to brands.

Operations

Compliance Monitoring

Endpoints for creators compliance data.

Operations

VwD External API (1.0.0)

Creator Management

Search and list creators

Request

Responses

Was this helpful?

Retrieve an creator's profile

Request

Responses

Was this helpful?

Explain a creator's VwD score

Request

Responses

Was this helpful?

Brand Management

List Management

Search

Account & Tokens

Content Analysis

Brand Mentions

Compliance Monitoring

VwD External API (1.0.0)

Creator Management

Search and list creators

RequestExpand all

Responses

Was this helpful?

Retrieve an creator's profile

Request

Responses

Was this helpful?

Explain a creator's VwD score

Request

Responses

Was this helpful?

Brand Management

List Management

Search

Account & Tokens

Content Analysis

Brand Mentions

Compliance Monitoring

Request