API Reference
/
Creator Discovery

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

Languages
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.

  1. GET /discovery/filters/ for the topics, industries and countries you can filter on.
  2. POST /discovery/search/ to find creators.
  3. POST /discovery/creators/add/?dry_run=true to see what adding them would cost.
  4. 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

Search Discovery CreatorsPreview

Request

Public API Endpoint

Searches creators you do not have yet: anyone already in your organization is left out.

Free text. q is parsed into filters, and applied_filters in the response shows what was applied. Parsing can differ between identical queries. For a repeatable result, set skip_parse: true, or send applied_filters back as filters. Anything you set in filters wins over what was parsed from q.

Audience questions are ignored. Audience demographics are not available through this API, so a question like "creators whose audience is mostly in the UK" returns creators without that filter. Check applied_filters to see what was applied.

Send JSON. filters cannot be sent in a form-encoded body. A field this route does not know is refused with 400, so a typo cannot quietly search everyone and spend your limits.

Each creator returned counts towards your daily and monthly result limits. Limited preview: requires an API key enabled for this route.

Bodyapplication/json
qstring<= 500 characters

Free text, parsed into filters unless skip_parse or exact is set. Empty browses by popularity.

Default ""
exactboolean

Phrase-match name and summary only.

Default false
skip_parseboolean

Do not parse q into filters. Parsing can differ between identical queries.

Default false
orderingstring

A leading - sorts descending. Defaults to relevance.

Enum"relevance""-relevance""followers""-followers""engagement_rate""-engagement_rate""created_at""-created_at"
pageinteger>= 1
Default 1
page_sizeinteger[ 1 .. 50 ]
Default 10
filtersobject(DiscoveryFilters)

Applied on top of q, and they win over anything parsed from it.

curl -i -X POST \
  https://api.vwd.ai/api/public/v1/discovery/search/ \
  -H 'Authorization: Api-Key YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "q": "female fitness creators in France",
    "page_size": 20
  }'

Responses

One page of matching creators.

Bodyapplication/json
countintegerrequired

Creators matching the search.

Example: 2
reachable_countintegerrequired

How many of those paging can reach, under the depth limit.

Example: 2
total_pagesintegerrequired
Example: 1
pageintegerrequired
Example: 1
page_sizeintegerrequired
Example: 20
applied_filtersobjectrequired

The filters actually applied, including any parsed from q.

Example: {"gender":"female","topic":"fitness","country":"France"}
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
Response
application/json
{
  "count": 2,
  "reachable_count": 2,
  "total_pages": 1,
  "page": 1,
  "page_size": 20,
  "applied_filters": {
    "gender": "female",
    "topic": "fitness",
    "country": "France"
  },
  "results": [
    { … }
  ]
}

List Discovery Filter ValuesPreview

Request

Public API Endpoint

The topics, industries and countries that the search filters accept, each with its creator count. Use slug for topic and industry, and country exactly as listed. Limited preview: requires an API key enabled for this route.

curl -i -X GET \
  https://api.vwd.ai/api/public/v1/discovery/filters/ \
  -H 'Authorization: Api-Key YOUR_API_KEY_HERE'

Responses

The filter values.

Bodyapplication/json
topicsArray of objectsrequired
topics[].​slugstringrequired
Example: "fitness"
topics[].​namestringrequired
Example: "Fitness"
topics[].​countintegerrequired
Example: 15230
industriesArray of objectsrequired
industries[].​slugstringrequired
Example: "lifestyle"
industries[].​namestringrequired
Example: "Lifestyle"
industries[].​countintegerrequired
Example: 48110
countriesArray of objectsrequired
countries[].​countrystringrequired
Example: "France"
countries[].​countintegerrequired
Example: 9120
Response
application/json
{
  "topics": [
    { … }
  ],
  "industries": [
    { … }
  ],
  "countries": [
    { … }
  ]
}

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"
  ]
}

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