Understanding Creator Data

A creator represents a person or brand. A profile represents one of their social accounts. Use creator IDs to work with a person, and platform usernames to work with a specific account. The creator and profile endpoints return Instagram accounts. Use live platform data to research Instagram, TikTok, and YouTube resources.

Retrieve a creator and their profiles

Set CREATOR_ID to an ID returned by search, lookalikes, or profile lookup:

curl --fail-with-body --silent --show-error \
  "https://api.influship.com/v1/creators/$CREATOR_ID?include=profiles" \
  -H "X-API-Key: $INFLUSHIP_API_KEY"

The response’s data contains the creator; data.profiles contains their linked profiles. One creator can have multiple linked Instagram accounts. The Creator reference defines the full response.

Starting input	Request	ID to keep
A brief	`POST /v1/search`	`data[].creator.id`
An Instagram username	`GET /v1/profiles/instagram/{username}`	The profile’s `creator_id`
Several Instagram usernames	`POST /v1/profiles/lookup`	Each resolved profile’s `creator_id`
A creator ID	`GET /v1/creators/{id}?include=profiles`	The creator’s `id` and linked profile usernames

Use batch profile lookup for an existing handle list. Search returns both relevant_profile (the account most relevant to the query) and primary_profile (the largest account); either can be null.

Read freshness timestamps

Keep collection time separate from analysis time when displaying or caching data.

Field	Meaning
Profile `data_updated_at`	When the profile data was updated; nullable
Creator `analysis_updated_at`	When the creator analysis was updated; nullable
TikTok `scraped_at`	Collection timestamp returned by the live TikTok endpoint
Shortlist `updated_at`	When the saved list changed; independent of creator metrics

Live endpoints can reuse recently collected source data. Check the endpoint’s returned timestamp against your application’s freshness requirement. A missing timestamp means the collection time is unknown. A saved shortlist keeps profile references, rather than a frozen copy of their metrics. Reopen those references with profile lookup to retrieve the latest stored data.

Display missing data

Field or result	Display or follow-up
Numeric metric is `null`	Show “Unknown” or omit it; zero means an observed zero
`relevant_profile` or `primary_profile` is `null`	Show the creator’s available details; retrieve linked profiles when needed
`location_unverified` is `true`	Label the location as unverified
Search uses `retrieval_fallback`	Label the result as a discovery candidate; see search quality
Stored profile lookup misses a handle	Add it through on-demand ingestion
Media URL has expired	Fetch a new URL using the platform guide

For partial records after ingestion, follow the bounded polling example. For failed requests, follow Error Handling.

Start building

Find and evaluate creators

Research and save

Apps and workflows

Live platform data

Connect your tools

Operate your integration

Understanding Creator Data

Retrieve a creator and their profiles

Read freshness timestamps

Display missing data

​Retrieve a creator and their profiles

​Read freshness timestamps

​Display missing data

Retrieve a creator and their profiles

Read freshness timestamps

Display missing data