Add Discovery Creators

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

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

Creator Discovery

Find creators you do not have yet, see what adding them costs, and add them.

Preview, coming soon. Creator Discovery through the API is not generally available yet. It is in a limited preview, and details may change before release. Until then, these routes answer 403 endpoint_disabled for API keys outside the preview.

The usual flow.

GET /discovery/filters/ for the topics, industries and countries you can filter on.
POST /discovery/search/ to find creators.
POST /discovery/creators/add/?dry_run=true to see what adding them would cost.
POST /discovery/creators/add/ to add them, then GET /creators/{id}/ with each influencer_id.

Result limits. Each creator returned by search or by GET /discovery/creators/ counts towards your organization's daily and monthly limits. The request that crosses a limit is still served in full, and the next one gets 429. The daily limit resets at midnight UTC and stops all results. The monthly limit only stops paging further into a result set, so page 1 of a new search still works. These routes also count towards your organization's API rate limit.

Operations

Get Discovery Creators by IDPreview

Request

Public API Endpoint

Returns the same creator objects as search, for ids you already hold. An id that is no longer in Discovery, or that search would not show, comes back in unavailable_ids.

A creator today's search already returned is not counted again. Any other creator returned counts towards your daily and monthly result limits. Limited preview: requires an API key enabled for this route.

Query

idsstringrequired

Comma-separated creator ids, from 1 to 100.

Example: ids=disc-122640,plat-4866

curl -i -X GET \
  'https://api.vwd.ai/api/public/v1/discovery/creators/?ids=disc-122640%2Cplat-4866' \
  -H 'Authorization: Api-Key YOUR_API_KEY_HERE'

Responses

The creators found, and the ids that were not.

Bodyapplication/json

resultsArray of objects(DiscoveryCreator)required

results[].idstringrequired

Typed creator id, disc-<id> or plat-<id>, as POST /discovery/creators/add/ takes it. The two id spaces overlap, so always keep the prefix.

Example: "disc-122640"

results[].influencer_idinteger or nullrequired

Your creator id, when you already have this creator.

Example: null

results[].is_addedbooleanrequired

Whether this creator is already in your organization.

Example: false

results[].namestringrequired

Example: "Eva Run"

results[].summarystringrequired

Example: "Endurance coach sharing marathon training plans."

results[].regionstringrequired

Example: "europe"

results[].countrystringrequired

Example: "France"

results[].citystringrequired

Example: "Lyon"

results[].genderstringrequired

Empty when unknown.

Example: "female"

results[].profile_picstringrequired

Image URL. Empty when there is none.

results[].followers_reachintegerrequired

Followers across the creator's platforms.

Example: 120000

results[].avg_likes_per_postnumberrequired

Example: 3400.5

results[].avg_views_per_videonumberrequired

Example: 18250

results[].avg_comments_per_postnumberrequired

Example: 96.2

results[].platformsArray of objectsrequired

results[].platforms[].platformstringrequired

Example: "instagram"

results[].platforms[].profile_idstringrequired

The handle on that platform.

Example: "evarun"

results[].platforms[].profile_urlstringrequired

Example: "https://instagram.com/evarun"

results[].platforms[].followers_countinteger or nullrequired

null when the count is not known yet.

Example: 120000

results[].topicsArray of stringsrequired

Example: ["Fitness","Running"]

results[].industriesArray of stringsrequired

Example: ["Lifestyle"]

results[].created_atstring(date-time)required

unavailable_idsArray of stringsrequired

Ids no longer in Discovery, or that search would not show.

Example: ["disc-99999999"]

Response

application/json

{
  "results": [
    { … }
  ],
  "unavailable_ids": [
    "disc-99999999"
  ]
}

Add Discovery CreatorsPreview

Request

Public API Endpoint

Adds creators to your organization and starts their scan, spending tokens per creator as POST /creators/ does. Use influencer_id from the result with GET /creators/{id}/.

Read the status of each creator. The response is 200 even when some creators fail, and one failing does not affect the others:

promoted: added, and the scan is started. Tokens were spent.
already_promoted: you already have this creator. No tokens were spent. influencer_id can be null here, when the creator was matched by profile URL only.
failed: not added and not charged. detail says why.

Sending again is safe. A creator added earlier comes back already_promoted without a second charge. A batch that runs long stops starting new creators, and if scans cannot be started right now every creator comes back failed. Those were not charged and can be sent again.

Previewing cost. With ?dry_run=true nothing is added or charged, and a cost quote is returned. The quote prices every id in the request, including repeats and creators you already have, which a real add does not charge for. Your balance is checked the same way up front, so a batch can get 402 even if some of its ids would be free.

A parameter or field this route does not know is refused with 400, so ?dry_run=tru cannot turn into a real add. Limited preview: requires an API key enabled for this route.

Query

dry_runstring

true or 1 returns a cost quote with no side effects. false or 0 is a real add. Any other value is refused with 400.

Example: dry_run=true

Bodyapplication/jsonrequired

idsArray of strings[ 1 .. 100 ] itemsrequired

Typed creator ids, as search returns them. A bare number is refused.

scan_typestring

A scan tier slug. Read GET /scan-catalog/ for the tiers and their costs.

Default "scan_full"

Example: "scan_1y"

monitoringboolean

Also turn on monitoring, which costs more tokens now and at every anniversary.

Default false

curl -i -X POST \
  'https://api.vwd.ai/api/public/v1/discovery/creators/add/?dry_run=true' \
  -H 'Authorization: Api-Key YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": [
      "disc-122640",
      "plat-4866"
    ],
    "scan_type": "scan_1y",
    "monitoring": false
  }'

Responses

The result for each creator, or the cost quote with ?dry_run=true.

Bodyapplication/json

One of:

resultsArray of objectsrequired

results[].idstringrequired

The id exactly as you sent it.

Example: "disc-122640"

results[].statusstringrequired

Enum"promoted""already_promoted""failed"

results[].detailstringrequired

Why it failed. Empty otherwise.

results[].influencer_idinteger or nullrequired

Your creator id. null on failed, or if an already_promoted creator matched by profile URL only.

Example: 981

successbooleanrequired

true when the request ran. Read each creator's status for the outcome.

Example: true

Response

application/json

{
  "results": [
    { … },
    { … },
    { … }
  ],
  "success": true
}

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

Brand Management

List Management

Search

Creator Discovery

Get Discovery Creators by IDPreview

Request

Responses

Was this helpful?

Add Discovery CreatorsPreview

Request

Responses

Was this helpful?

Account & Tokens

Content Analysis

Brand Mentions

Compliance Monitoring