Create Discovery

Creates a new discovery and automatically starts the build process, if no errors were found.

Every call to this endpoint consumes an API credit. If the discovery process fails, the credit will be refunded to the company automatically.

The caller must have the discovery permission to use this endpoint.

Getting Started

URL REQUEST (POST)

https://api.statsocial.com/platform/v0/discoveries

Main Parameters

Required Fields

Field	Type	Description
name	string	Name of the discovery
entity_type	string	Type of entity: creators, brands, or media
type	string	Discovery type: audience, topic, or shared_audience
network	object	At least one network must be enabled
followers_min	integer	Minimum follower count (minimum value: 10000)

Optional Fields

Field	Type	Description
ss_id_key	string	Required for shared_audience and topic types. For topics, use one of the available topic values
audience_id	integer	Required for audience and shared_audience types
followers_max	integer	Maximum follower count
gender	string	Filter by gender: male, female, or other
age	array	Filter by age ranges (e.g., ["18-24", "25-34"])
country	array	Filter by country codes (e.g., ["US", "UK"])

Network Object

{
    "network": {
        "tik_tok": true,
        "instagram": true,
        "youtube": false,
        "twitter": false,
        "bluesky": false
    }
}

At least one network must be set to true.

Available Topics

For type: "topic", use one of these values in ss_id_key:

academics, animals, art, authors, automotive, business, comedy, entertainment, esports, family, fashion, film, food, health, home, music, news, politics, religion, science, sports, travel

Let's go to examples

Create Discovery from Shared Audience

In this example we create a discovery to find creators based on a shared audience file.

URL REQUEST (POST)

https://api.statsocial.com/platform/v0/discoveries

With this payload:

{
    "name": "My Creator Discovery",
    "entity_type": "creators",
    "ss_id_key": "/uploads/2024-01-15/078ace94fad569f01d1a3a99a440cf5c.ssid",
    "type": "shared_audience",
    "audience_id": 12345,
    "network": {
        "tik_tok": true,
        "instagram": true,
        "youtube": false,
        "twitter": false,
        "bluesky": false
    },
    "followers_min": 10000,
    "followers_max": 1000000,
    "gender": "female",
    "age": ["18-24", "25-34"],
    "country": ["US", "UK"]
}

We will receive a json like this:

{
    "response": {
        "id": 123,
        "status": "running"
    },
    "information": {
        "version": "0.0.1"
    }
}

Create Discovery by Topic

In this example we create a discovery to find sports-related creators.

URL REQUEST (POST)

https://api.statsocial.com/platform/v0/discoveries

With this payload:

{
    "name": "Sports Creators Discovery",
    "entity_type": "creators",
    "ss_id_key": "sports",
    "type": "topic",
    "network": {
        "tik_tok": false,
        "instagram": true,
        "youtube": true,
        "twitter": false,
        "bluesky": false
    },
    "followers_min": 50000,
    "gender": "male",
    "country": ["US"]
}

We will receive a json like this:

{
    "response": {
        "id": 124,
        "status": "running"
    },
    "information": {
        "version": "0.0.1"
    }
}