openapi: 3.0.3
info:
  title: Core API Concepts
  version: 1.0.0
  description: >
    **Authentication**


    Every request is authenticated by a Bearer credential in the `Authorization`
    header. There are two types of credential, each suited to a different use
    case:


    - **[API Keys](/openapi/api-keys)** — call the API as yourself (scripts,
    backend services). Create and revoke them in the dashboard or via the API;
    you can hold several and revoke any one independently.

    - **[OAuth](/openapi/oauth)** — for applications acting on behalf of other
    users (desktop or CLI tools), via OAuth 2.0 with PKCE.


    Each credential carries one or more scopes that control what it can access.
    Today every credential is issued with full access; scoped, least-privilege
    credentials are planned.


    **Discovery**


    Identify and evaluate creators using structured, platform-specific search
    criteria.

    Responses are intentionally constrained to support ranking, filtering, and
    selection

    at scale rather than full profile hydration.


    **Enrichment**


    Retrieve complete creator-level data once a candidate has been identified.

    Enrichment responses provide the depth required for analysis, activation,

    and downstream data workflows.


    **Execution modes**


    Enrichment is available in both synchronous and asynchronous forms.

    Single enrichment supports real-time use cases, while batch enrichment is
    optimized

    for high-throughput, non-interactive processing.


    **Typical usage**


    Discovery and enrichment are designed as complementary stages.

    Discovery narrows the candidate set; enrichment supplies detailed data

    for creators that have already been qualified.
paths:
  /public/v1/creators/content/posts/:
    post:
      operationId: public_v1_creators_content_posts_create
      description: >-
        Fetch recent posts for a creator on a given platform.


        **What you get**


        - Returns a list of recent posts with metadata including post ID, URL,
        caption, media URLs, timestamps, and engagement metrics (likes,
        comments, views, shares).

        - Supports Instagram, TikTok, and YouTube platforms.

        - Uses cursor-based pagination via `next_token` for fetching additional
        pages of results.

        - Page sizes are platform-specific:

        &nbsp;&nbsp;**Instagram** — fixed at 12 posts per page (not
        configurable).

        &nbsp;&nbsp;**TikTok** — default 30, max 35.

        &nbsp;&nbsp;**YouTube** — default 30, max 50.


        **Credits**


        - 0.03 credits per successful request. If no data is returned, no
        credits are deducted.


        <div class="ic-ai-prompt-root" data-endpoint="creator-posts"></div>
      summary: Creator Posts
      tags:
        - Creator Posts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatorPostsQuery'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreatorPostsQuery'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreatorPostsQuery'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorPostsResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        0.03 credits per successful request. If no data is returned, no credits
        are deducted.
  /public/v1/creators/content/details/:
    post:
      operationId: public_v1_creators_content_details_create
      description: >-
        Retrieve detailed information about specific creator content.


        **What you get**


        - Supports Instagram, TikTok, and YouTube platforms.

        - Returns platform-specific content metadata and engagement data in a
        structured format.


        **Supported content types per platform**


        - **Instagram**: `data`, `comments`, `transcript`, `audio`

        - **TikTok**: `data`, `comments`, `transcript`, `audio`

        - **YouTube**: `data`, `comments`, `transcript`


        **Credits**


        - 0.03 credits per successful request. If no data is returned, no
        credits are deducted.


        **When to use**


        Use this endpoint when you have a specific post ID and need to go deeper
        than profile-level data. Typical use cases: brand safety review,
        transcript extraction for content analysis, pulling comment threads, and
        engagement deep-dives on individual posts.


        **Result format**


        The `result` field returns a platform-specific object:

        - `data` — post metadata and engagement stats (likes, views, shares)

        - `comments` — paginated comment list; use `pagination_token` to fetch
        the next page

        - `transcript` — spoken text extracted from the video

        - `audio` — audio resource reference (Instagram and TikTok only)


        <div class="ic-ai-prompt-root" data-endpoint="post-details"></div>
      summary: Post Details
      tags:
        - Post Details
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatorContentDetailsRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreatorContentDetailsRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreatorContentDetailsRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorContentDetailsResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        0.03 credits per successful request. If no data is returned, no credits
        are deducted.
  /public/v1/creators/socials/:
    post:
      operationId: public_v1_creators_socials_create
      description: >-
        Discover all verified social accounts connected to a creator, given a
        seed platform and handle.


        **What you get**


        - Returns an array of verified connected social accounts across
        platforms, including platform name, username, and follower count for
        each connected account.

        - Supports 6 seed platforms: Instagram, YouTube, TikTok, OnlyFans,
        Twitter, and Twitch.


        **Credits**


        - 0.5 credits per successful request. If no data is returned, no credits
        are deducted.


        <div class="ic-ai-prompt-root" data-endpoint="connected-socials"></div>
      summary: Connected Socials
      tags:
        - Connected Socials
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectedSocialsQuery'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ConnectedSocialsQuery'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ConnectedSocialsQuery'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectedSocialsResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        0.5 credits per successful request. If no data is returned, no credits
        are deducted.
  /public/v1/creators/enrich/handle/full/:
    post:
      operationId: public_v1_creators_enrich_handle_full_create
      description: >-
        Perform comprehensive enrichment of a creator profile using their social
        media handle.


        **What you get**


        - Returns complete profile data including cross-platform presence,
        engagement analytics, follower growth metrics, content performance data,
        monetization indicators, niche classification, hashtags, income
        estimates, and optional lookalike creator recommendations.

        - Supports Instagram, YouTube, TikTok, OnlyFans, Twitter, Snapchat,
        Discord, Pinterest, Facebook, LinkedIn, and Twitch platforms.

        - Optional email requirement and lookalike inclusion settings available.

        - Need only part of this? Use [Enrich by handle
        profile](/openapi/enrich-by-handle-profile) for identity and contact
        fields (0.2 credits) or [Enrich by handle
        analytics](/openapi/enrich-by-handle-analytics) for performance data
        (0.8 credits).


        **Credits**


        - 1 credit per successful request. If no data is returned, no credits
        are deducted.


        <div class="ic-ai-prompt-root" data-endpoint="handle-full"></div>
      summary: Enrich by handle full
      tags:
        - Enrich by handle full
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichFullHandleRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EnrichFullHandleRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EnrichFullHandleRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFullPlatformResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        1 credit per successful request. If no data is returned, no credits are
        deducted.
  /public/v1/creators/enrich/handle/profile/:
    post:
      operationId: public_v1_creators_enrich_handle_profile_create
      description: >-
        Enrich a creator profile with identity, contact, and vetting data using
        their social media handle.


        **What you get**


        - Returns the identity/contact/vetting subset of the [Enrich by handle
        full](/openapi/enrich-by-handle-full) response: validated email, name,
        gender, location, cross-platform presence, and core profile/vetting
        fields (verification, account type, follower/media counts, bio, niche
        classification).

        - No deeper performance data — no growth curves, medians, income
        estimates or audience demographics. Use [Enrich by handle
        analytics](/openapi/enrich-by-handle-analytics) for those. Instagram,
        YouTube, TikTok, OnlyFans and Twitter do include a headline
        `engagement_percent`.

        - Works with all 11 platforms: Instagram, YouTube, TikTok, OnlyFans,
        Twitter, Twitch, Snapchat, Discord, Pinterest, Facebook and LinkedIn.
        Facebook, Pinterest, Snapchat, Discord and LinkedIn carry basic identity
        data only — there is no analytics counterpart for them.

        - Optional email requirement setting available.


        **Credits**


        - 0.2 credits per successful request. If no data is returned, no credits
        are deducted. If `email_required` is `must_have` and no valid email is
        found, no credits are deducted.


        <div class="ic-ai-prompt-root" data-endpoint="handle-profile"></div>
      summary: Enrich by handle profile
      tags:
        - Enrich by handle profile
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichProfileHandleRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EnrichProfileHandleRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EnrichProfileHandleRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleProfilePlatformResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        0.2 credits per successful request. If no data is returned, no credits
        are deducted. If email_required is must_have and no valid email is
        found, no credits are deducted.
  /public/v1/creators/enrich/handle/analytics/:
    post:
      operationId: public_v1_creators_enrich_handle_analytics_create
      description: >-
        Enrich a creator profile with performance analytics using their social
        media handle.


        **What you get**


        - Returns the performance-analytics subset of the [Enrich by handle
        full](/openapi/enrich-by-handle-full) response: engagement/growth
        detail, posting frequency, income estimates, audience data, and optional
        lookalike creator recommendations.

        - No identity or contact fields, including email. Use [Enrich by handle
        profile](/openapi/enrich-by-handle-profile) for those.

        - Works with Instagram, YouTube, TikTok, OnlyFans, Twitter and Twitch.

        - Facebook, Pinterest, Snapchat, Discord and LinkedIn have no analytics
        data and are rejected with a `400`. Use [Enrich by handle
        profile](/openapi/enrich-by-handle-profile) for those.

        - Optional lookalike inclusion setting available.


        **Credits**


        - 0.8 credits per successful request. If no data is returned, no credits
        are deducted.


        <div class="ic-ai-prompt-root" data-endpoint="handle-analytics"></div>
      summary: Enrich by handle analytics
      tags:
        - Enrich by handle analytics
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichAnalyticsHandleRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EnrichAnalyticsHandleRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EnrichAnalyticsHandleRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleAnalyticsPlatformResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        0.8 credits per successful request. If no data is returned, no credits
        are deducted.
  /public/v1/creators/enrich/handle/raw/:
    post:
      operationId: public_v1_creators_enrich_handle_raw_create
      description: >-
        Retrieve raw platform data for a creator profile using their social
        media handle.


        **What you get**


        - Returns unprocessed platform-specific data directly from the source,
        including basic profile information, post data, media counts, and
        platform-native metadata.

        - This endpoint provides the foundational data layer before any
        additional processing or enrichment.

        - Supports Instagram, YouTube, TikTok, OnlyFans, Twitter, Snapchat,
        Discord, Pinterest, Facebook, and LinkedIn platforms.


        **Credits**


        - 0.03 credits per successful request. If no data is returned, no
        credits are deducted.


        <div class="ic-ai-prompt-root" data-endpoint="handle-raw"></div>
      summary: Enrich by handle raw
      tags:
        - Enrich by handle raw
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichRawHandleRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EnrichRawHandleRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EnrichRawHandleRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleRawPlatformResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        0.03 credits per successful request. If no data is returned, no credits
        are deducted.
  /public/v1/creators/enrich/email/:
    post:
      operationId: public_v1_creators_enrich_email_create
      description: >-
        Perform basic enrichment of creator profiles using an email address.


        **What you get**


        - Returns the creator's single strongest platform — the one with the
        highest follower count — with essential profile data: basic social media
        presence, contact details, and platform account identifiers.

        - Ideal for quick profile lookups and initial creator identification
        across Instagram, YouTube, TikTok, Twitter, Twitch, and OnlyFans.


        **Credits**


        - 0.05 credits per successful request. If no data is returned, no
        credits are deducted.


        <div class="ic-ai-prompt-root" data-endpoint="email"></div>
      summary: Enrich by email
      tags:
        - Enrich by email
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichBasicEmailRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EnrichBasicEmailRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EnrichBasicEmailRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleEmailResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        0.05 credits per successful request. If no data is returned, no credits
        are deducted.
  /public/v1/discovery/:
    post:
      operationId: public_v1_discovery_create
      description: >-
        Search and discover creators across multiple platforms using advanced
        filtering and search.


        **What you get**


        - Paginated list of creator profiles with profile info, follower counts,
        engagement rates, and analytics. Instagram creators (10k+ followers)
        also include audience demographics and interest data.

        - Supports Instagram, YouTube, TikTok, Twitch, Twitter, and OnlyFans
        platforms.


        **Platform-specific filters**


        - The available filters depend on the `platform` you choose — switching
        `platform` changes the filter fields in the request body.

        - Use the Dictionary endpoints to retrieve valid values for filters such
        as locations, languages, brands, audience interests, and audience
        locations.


        **Natural-language search**


        - Optional — `filters` work on their own. Sending an `nlp_search` brief
        lets you describe who you're looking for in plain language instead of
        building filters by hand, and you can combine the two.

        - The 200 response adds `applied_filters` (what the search actually ran
        with) and `nlp_search` (what the AI inferred, and why anything was
        dropped).


        **Credits**


        - **0.01 credits per creator returned** — 0 creators, 0 credits.

        - Every request that returns creators is billed, even with identical
        filters. Monitoring your request volume and credit usage is your
        responsibility.

        - Usage is capped per billing period — see [Usage &
        limits](guides/usage-limits.md#discovery-fair-use-cap) for how the cap
        works and what happens when you reach it.


        **Premium: matched filter values**


        - `return_filter_values=true` — each returned creator includes a
        `matched_filters` object showing exactly which of your filter values it
        matched; see its schema in the 200 response for the shape of each field.
        0.03 credits per creator instead of 0.01, and the unique-handle cap is
        unchanged. See [the
        FAQ](/guides/faq#can-i-see-which-filter-values-each-creator-matched) for
        an example.


        <div class="ic-ai-prompt-root" data-endpoint="discovery"></div>
      summary: Discovery API
      parameters:
        - in: query
          name: return_filter_values
          schema:
            type: boolean
          description: Include a matched_filters object on each returned creator.
          required: false
      tags:
        - Discovery API
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoveryAPISearchInputRequest'
            example:
              platform: instagram
              nlp_search: fitness creators in New York with over 100k followers
              filters:
                location:
                  - United States
                number_of_followers:
                  min: 1000
                profile_language:
                  - en
                engagement_percent:
                  min: 0.5
              sort:
                sort_by: relevancy
                sort_order: desc
              paging:
                limit: 10
                page: 0
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DiscoveryAPISearchInputRequest'
            example:
              platform: instagram
              nlp_search: fitness creators in New York with over 100k followers
              filters:
                location:
                  - United States
                number_of_followers:
                  min: 1000
                profile_language:
                  - en
                engagement_percent:
                  min: 0.5
              sort:
                sort_by: relevancy
                sort_order: desc
              paging:
                limit: 10
                page: 0
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DiscoveryAPISearchInputRequest'
            example:
              platform: instagram
              nlp_search: fitness creators in New York with over 100k followers
              filters:
                location:
                  - United States
                number_of_followers:
                  min: 1000
                profile_language:
                  - en
                engagement_percent:
                  min: 0.5
              sort:
                sort_by: relevancy
                sort_order: desc
              paging:
                limit: 10
                page: 0
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoverySearchResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Bad Request — invalid or missing parameters. Also returned when an
            `nlp_search` brief cannot be interpreted into filters ("Your search
            couldn't be interpreted into filters"), in which case nothing is
            charged.
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Service Error — a downstream dependency failed. Safe to retry.
            Returned when the AI mapping service behind `nlp_search` is
            temporarily unavailable.
      x-credits: >-
        0.01 credits per creator returned. If no creators are returned, no
        credits are deducted.
  /public/v1/discovery/classifier/languages/:
    get:
      operationId: public_v1_discovery_classifier_languages_list
      description: >-
        Retrieve a list of supported languages with their abbreviations for
        filtering creators by profile language or content language. Useful for
        discovering creators who create content in specific languages or target
        particular linguistic audiences.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Languages
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Language'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/classifier/locations/{platform}/:
    get:
      operationId: public_v1_discovery_classifier_locations_retrieve
      description: >-
        Retrieve a list of location identifiers available for a specific
        platform.


        **What you get**


        - Returns location strings that can be used to filter creators by
        geographic location in discovery searches.

        - Platform-specific location data helps target creators from specific
        regions, cities, or countries.

        - Use the `search` parameter for substring/prefix matching on location
        names (e.g. "London", "United").

        - Use `offset` and `limit` to paginate through results.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Platform Locations
      parameters:
        - in: query
          name: search
          schema:
            type: string
          description: Search string to filter results
          required: false
        - in: query
          name: offset
          schema:
            type: integer
          description: Cursor offset for pagination
          required: false
        - in: query
          name: limit
          schema:
            type: integer
          description: Number of results to return per page (1-100)
          required: false
        - in: path
          name: platform
          schema:
            type: string
          required: true
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
          description: A list of strings representing platform details
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/classifier/brands/:
    get:
      operationId: public_v1_discovery_classifier_brands_list
      description: >-
        Returns brands that can be used in the `brands` filter on the Discovery
        API, to find creators who have worked with a brand or mentioned it in
        their content. Each entry has the brand's `username`, display name
        (`full_name`) and a normalised name (`cleaned`).


        **What you get**


        - Results come in pages, not a complete list. Add your `limit` to
        `offset` for the next page — the full `limit`, even if fewer come back,
        or you will get repeats. Short pages are normal, because duplicates and
        brands with a social network in the name are dropped after paging, so
        keep going until you get an empty response.

        - Pass the `username` value into the `brands` filter on the Discovery
        API. The filter matches against `username`, so sending a display name
        returns a 400.


        **Searching**


        - By default, `search` matches a brand's `username` exactly. Use it to
        confirm a `username` before filtering on it.

        - Add `exact=false` to match part of a brand's `cleaned` name instead —
        the normalised value returned with each entry, not `full_name`. For
        example, `?search=kfc&exact=false` returns "KFC UK & Ireland", which
        `?search=kfc` on its own does not.

        - `cleaned` drops accents, punctuation and emoji, transliterates
        non-Latin scripts, and is often shorter than the display name: "L'Oréal
        Professionnel Paris" is `Loreal`, "Walt Disney World" is `Disney`. Match
        against the `cleaned` values you get back, not the display name.

        - `search` is matched case-insensitively, and the wildcard characters
        `*`, `?` and `\` are ignored.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Brands
      parameters:
        - in: query
          name: search
          schema:
            type: string
            default: ''
          description: >-
            The brand's `username`. Must match exactly unless you set
            `exact=false`.
          required: false
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Where to start in the results. Add your `limit` for the next page.
          required: false
        - in: query
          name: limit
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
          description: How many brands to return per page.
          required: false
        - in: query
          name: exact
          schema:
            type: boolean
            default: true
          description: >-
            When true (the default), `search` must match a brand's `username`
            exactly. Set to false to match part of the brand's normalised
            `cleaned` name instead, which is not the same as its display name.
          required: false
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/classifier/yt-topics/:
    get:
      operationId: public_v1_discovery_classifier_yt_topics_list
      description: >-
        Retrieve a hierarchical list of YouTube topic categories and their
        subtopics.


        **What you get**


        - Returns YouTube topic categories and their subtopics. When using
        YouTube Discovery, pass `sub_topic_details` values into the `topics`
        filter.

        - Useful for finding creators in particular content verticals or subject
        areas.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Youtube Topics
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/YouTubeTopic'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/classifier/games/:
    get:
      operationId: public_v1_discovery_classifier_games_list
      description: >-
        Retrieve a list of video games available on Twitch that can be used for
        filtering creators. Returns game identifiers and metadata to help
        discover Twitch streamers who play specific games or have streamed
        particular titles.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Twitch Games
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/YouTubeTopic'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/classifier/audience-brand-categories/:
    get:
      operationId: public_v1_discovery_classifier_audience_brand_categories_list
      description: >-
        Returns a list of audience brand categories (e.g., Sports, Fashion,
        Technology) from Instagram creator audience data. Use these values in
        the audience.brand_categories filter on the Discovery API to search for
        Instagram creators (10k+ followers) whose audience follows brands in
        specific categories.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Audience Brand Categories
      parameters:
        - in: query
          name: search
          schema:
            type: string
          description: Search string to filter results
          required: false
        - in: query
          name: offset
          schema:
            type: integer
          description: Cursor offset for pagination
          required: false
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/classifier/audience-brand-names/:
    get:
      operationId: public_v1_discovery_classifier_audience_brand_names_list
      description: >-
        Returns a list of audience brand names (e.g., Nike, Apple, Starbucks)
        from Instagram creator audience data. Use these values in the
        audience.brands filter on the Discovery API to search for Instagram
        creators (10k+ followers) whose audience follows specific brands.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Audience Brand Names
      parameters:
        - in: query
          name: search
          schema:
            type: string
          description: Search string to filter results
          required: false
        - in: query
          name: offset
          schema:
            type: integer
          description: Cursor offset for pagination
          required: false
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/classifier/audience-interests/:
    get:
      operationId: public_v1_discovery_classifier_audience_interests_list
      description: >-
        Returns a list of audience interest values from Instagram creator
        audience data. Use these values in the audience.interests filter on the
        Discovery API to search for Instagram creators (10k+ followers) whose
        audience has specific interests.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Audience Interests
      parameters:
        - in: query
          name: search
          schema:
            type: string
          description: Search string to filter results
          required: false
        - in: query
          name: offset
          schema:
            type: integer
          description: Cursor offset for pagination
          required: false
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/classifier/audience-locations/:
    get:
      operationId: public_v1_discovery_classifier_audience_locations_list
      description: >-
        Returns a list of audience location values (countries, states, cities)
        from Instagram creator audience data. Use these values in the
        audience.location filter on the Discovery API to search for Instagram
        creators (10k+ followers) whose audience is in specific locations.


        **Credits**


        - 0 credits. This endpoint does not deduct credits.
      summary: Audience Locations
      parameters:
        - in: query
          name: search
          schema:
            type: string
          description: Search string to filter results
          required: false
        - in: query
          name: offset
          schema:
            type: integer
          description: Cursor offset for pagination
          required: false
      tags:
        - Dictionary
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Brand'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/discovery/creators/similar/:
    post:
      operationId: public_v1_discovery_creators_similar_create
      description: >-
        Discover creators similar to a reference creator based on various
        similarity criteria.


        **What you get**


        - Returns a paginated list of creator profiles that match the reference
        creator's characteristics, content style, audience, or other specified
        attributes.

        - Supports filtering by URL, username, or ID, and allows additional
        filters to refine similarity matching.

        - Useful for finding lookalike creators, competitors, or creators in the
        same niche.


        **Credits**


        - **0.01 credits per creator returned**. If no creators are returned, no
        credits are deducted.

        - Credits are consumed on **every request** that returns creators, even
        if the filters are identical to a previous request.

        - It is the client's responsibility to monitor request volume and credit
        usage.

        - Similar-creator results count against the same per-billing-period
        Discovery cap. See [Usage &
        limits](guides/usage-limits.md#discovery-fair-use-cap).


        <div class="ic-ai-prompt-root" data-endpoint="similar"></div>
      summary: Similar Creators
      tags:
        - Similar Creators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichSimilarCreatorsRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EnrichSimilarCreatorsRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EnrichSimilarCreatorsRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryAPIResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        0.01 credits per creator returned. If no creators are returned, no
        credits are deducted.
  /public/v1/creators/audience/overlap/:
    post:
      operationId: public_v1_creators_audience_overlap_create
      description: >-
        Compare audience overlap between 2-10 creators on a given platform.


        **What you get**


        - Returns per-creator audience overlap and unique audience percentages,
        plus report-level totals (total followers and total unique followers
        across all compared creators).

        - Useful for evaluating creator partnerships, identifying audience
        duplication across campaigns, and optimizing influencer selection for
        maximum reach.


        **Credits**


        - 1 credit per request, regardless of how many creators are compared.


        <div class="ic-ai-prompt-root" data-endpoint="audience-overlap"></div>
      summary: Audience Overlap
      tags:
        - Audience Overlap
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudienceOverlapInput'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AudienceOverlapInput'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AudienceOverlapInput'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceOverlapResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 1 credit per request.
  /public/v1/enrichment/batch/:
    post:
      operationId: public_v1_enrichment_batch_create
      description: >-
        Create a batch enrichment job by uploading a CSV.


        **How it works**


        1. Upload a `.csv` file (one column: `handle` or `email`)

        2. Choose the enrichment mode (handle: `raw`/`full`, email: `basic`)

        3. Use the returned `batch_id` to check status and download results


        **Request**


        - `multipart/form-data`

        - `file`: CSV (max 10MB)

        - Mode fields depend on whether you’re enriching by `handle` or `email`


        **Credits**


        - Credits are deducted **per successfully enriched record**

        - The credit rate follows the corresponding single-enrichment pricing
        (handle `raw`/`full`, or email enrichment)

        - If no data is returned for a record, **0 credits** are deducted for
        that record


        **Checking completion**


        Poll `GET /public/v1/enrichment/batch/{batch_id}/status/` every 30–60
        seconds until the job finishes. Status values:

        - `queued` — waiting to start

        - `processing` — actively enriching records

        - `finished` — all records done; download results via `GET
        /public/v1/enrichment/batch/{batch_id}/`

        - `failed` — job failed

        - `paused_insufficient_credits` — top up credits and call the resume
        endpoint


        This API is polling-based. There are no webhooks or push notifications.


        <div class="ic-ai-prompt-root" data-endpoint="batch-create"></div>
      summary: Create Batch Enrichment
      tags:
        - Batch enrichment
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/BatchEnrichmentInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEnrichmentResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Total batch limit reached. You have 5 active batch(es).
                  Maximum 5 allowed.
                error_code: batch_limit_reached
                active_batches: 5
                max_allowed: 5
          description: Conflict — total active-batch capacity reached.
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Credits are deducted when batch records are processed successfully.
        Pricing follows the same credit model as the corresponding enrichment
        type: Handle enrichment (raw): 0.03 credits per successful record.
        Handle enrichment (full): 1 credit per successful record. Email
        enrichment: 0.05 credits per successful record. Creator content details:
        0.03 credits per successful record. Records that return no data do not
        deduct credits.
  /public/v1/enrichment/batch/{batch_id}/status/:
    get:
      operationId: public_v1_enrichment_batch_status_retrieve
      description: |-
        Check the current processing status of a batch enrichment job.

        **What you get**

        - Current state (e.g., queued/running/completed/failed)
        - Progress indicators (processed vs remaining), when available

        **Credits**

        - **0 credits** (status only)

        <div class="ic-ai-prompt-root" data-endpoint="batch-status"></div>
      summary: Get Batch Enrichment Status
      parameters:
        - in: path
          name: batch_id
          schema:
            type: string
          description: Unique batch identifier returned when creating the enrichment batch
          required: true
      tags:
        - Batch enrichment
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEnrichmentStatusResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Batch 'abc123' not found.
                error_code: batch_not_found
          description: Batch not found.
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/enrichment/batch/{batch_id}/resume/:
    post:
      operationId: public_v1_enrichment_batch_resume_create
      description: >-
        Resume a paused or interrupted batch enrichment job.


        **When to use**


        - If a batch was paused or failed mid-run and needs to continue
        processing


        **Credits**


        - **0 credits** to resume (credits apply only to successfully enriched
        records)


        <div class="ic-ai-prompt-root" data-endpoint="batch-resume"></div>
      summary: Resume Batch Enrichment
      parameters:
        - in: path
          name: batch_id
          schema:
            type: string
          description: Unique batch identifier returned when creating the enrichment batch
          required: true
      tags:
        - Batch enrichment
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Batch resumed successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Batch cannot be resumed. Current status is 'processing'.
                error_code: batch_not_resumable
                current_status: processing
          description: Bad Request — batch is not in a resumable state.
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Insufficient credits. Purchase additional credits or upgrade
                  your plan.
                error_code: insufficient_credits
                available_credits: 0.5
                required_minimum: 1
          description: Forbidden — not enough credits to resume the remaining work.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Batch 'abc123' not found.
                error_code: batch_not_found
          description: Batch not found.
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/enrichment/batch/{batch_id}/download/:
    get:
      operationId: public_v1_enrichment_batch_download_retrieve
      description: >-
        Download the enriched CSV dataset via a temporary presigned URL. **This
        is the recommended endpoint for downloading CSV results.**


        Compared to the direct download endpoint, this returns a short-lived URL
        that lets you download the file directly from storage — faster and more
        reliable for large files.


        **Requirements**


        - Batch must be in `finished` status

        - Results file must have been generated


        **Output format**


        - **CSV only** — for JSON output, use the direct download endpoint (`GET
        /public/v1/enrichment/batch/{batch_id}/`) with `?format=json`


        **Response**


        - `download_url` — temporary URL (valid for a limited time)

        - `expires_in` — seconds until the URL expires

        - `expires_at` — expiration timestamp


        **Error Responses**


        Every error response shares the canonical shape `{"error": <message>,
        "error_code": <slug>, ...}`. Branch programmatically on `error_code`
        rather than parsing `error`.


        - `400 Bad Request` (`error_code: "batch_not_ready"`) — batch not
        completed yet; `current_status` is included in the body

        - `400 Bad Request` (`error_code: "no_results"`) — batch finished but
        produced no rows

        - `400 Bad Request` (`error_code: "results_not_ready"`) — batch finished
        but the results file is still being assembled

        - `404 Not Found` (`error_code: "batch_not_found"`) — invalid batch ID
        or batch does not belong to client

        - `503 Service Unavailable` (`error_code: "feature_disabled"`) —
        presigned-URL downloads are currently disabled; use the direct download
        endpoint


        **Credits**


        - **0 credits** (download only)


        <div class="ic-ai-prompt-root" data-endpoint="batch-download-csv"></div>
      summary: Download Batch Enrichment CSV (Recommended)
      parameters:
        - in: path
          name: batch_id
          schema:
            type: string
          description: Unique batch identifier returned when creating the enrichment batch
          required: true
      tags:
        - Batch enrichment
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEnrichmentDownloadURL'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Batch not completed yet. Current status is 'processing'.
                error_code: batch_not_ready
                current_status: processing
          description: Bad Request — batch state prevents download.
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Batch 'abc123' not found.
                error_code: batch_not_found
          description: Batch not found.
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  This endpoint is not currently enabled. Please use the
                  standard download endpoint.
                error_code: feature_disabled
          description: >-
            Service Unavailable — the presigned-URL feature is currently
            disabled.
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/enrichment/batch/{batch_id}/:
    get:
      operationId: public_v1_enrichment_batch_retrieve
      description: >-
        Download the final enriched dataset after processing is complete.


        > **Tip:** For CSV downloads, consider using the **recommended**
        endpoint `GET /public/v1/enrichment/batch/{batch_id}/download/` instead
        — it returns a presigned URL for faster, more reliable downloads. Use
        this endpoint if you need **JSON** output or as a fallback.


        **Requirements**


        - Batch must be in `finished` status

        - Results file must have been generated


        **Output formats**


        - **CSV** (default) — omit `format` or pass `?format=csv`

        - **JSON** — pass `?format=json` to receive a JSON array where each
        object has:

        &nbsp;&nbsp;- `input_value` — the original input (handle or email)

        &nbsp;&nbsp;- `status` — enrichment status for that record

        &nbsp;&nbsp;- `enrichment_data` — the enriched creator data


        **Error Responses**


        Every error response shares the canonical shape `{"error": <message>,
        "error_code": <slug>, ...}`. Branch programmatically on `error_code`
        rather than parsing `error`.


        - `400 Bad Request` (`error_code: "batch_not_ready"`) — batch not
        completed yet; `current_status` is included in the body

        - `400 Bad Request` (`error_code: "no_results"`) — batch finished but
        produced no rows

        - `400 Bad Request` (`error_code: "results_not_ready"`) — batch finished
        but the results file is still being assembled

        - `404 Not Found` (`error_code: "batch_not_found"`) — invalid batch ID
        or batch does not belong to client

        - `500 Server Error` (`error_code: "service_error"`) — results file
        could not be retrieved from storage; safe to retry


        **Credits**


        - **0 credits** (download only)


        <div class="ic-ai-prompt-root" data-endpoint="batch-download"></div>
      summary: Download Batch Enrichment Results (Direct)
      parameters:
        - in: path
          name: batch_id
          schema:
            type: string
          description: Unique batch identifier returned when creating the enrichment batch
          required: true
        - in: query
          name: format
          schema:
            type: string
            enum:
              - csv
              - json
            default: csv
          description: >-
            Output format. Omit or pass `csv` (default) to receive a CSV file.
            Pass `json` to receive a JSON array of objects with `input_value`,
            `status`, and `enrichment_data` fields.
          required: false
          example: csv
      tags:
        - Batch enrichment
      security:
        - Bearer: []
      responses:
        '200':
          description: >-
            CSV or JSON file with enriched results depending on the `format`
            query parameter.
          content:
            text/csv:
              schema:
                type: string
                format: binary
                description: Default CSV file with enriched results
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    input_value:
                      type: string
                    status:
                      type: string
                    enrichment_data:
                      type: object
                      additionalProperties: true
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Batch not completed yet. Current status is 'processing'.
                error_code: batch_not_ready
                current_status: processing
          description: Bad Request — batch state prevents download.
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Batch 'abc123' not found.
                error_code: batch_not_found
          description: Batch not found.
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Failed to retrieve results file. Please retry in a few
                  minutes.
                error_code: service_error
          description: Server Error — results file could not be retrieved from storage.
      x-credits: 0 credits. This endpoint does not deduct credits.
  /public/v1/accounts/credits/:
    get:
      operationId: account_credits_usage_retrieve
      description: |-
        Use your API key to check your remaining credits and total credits used.

        **Response fields**

        - `credits_available` — remaining credits
        - `credits_used` — total credits consumed

        **Credits**

        - **0 credits**

        <div class="ic-ai-prompt-root" data-endpoint="account-credits"></div>
      summary: Check account credits and usage details
      tags:
        - Account credits & usage
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  credits_available:
                    type: number
                  credits_used:
                    type: number
                required:
                  - credits_available
                  - credits_used
              example:
                credits_available: 0
                credits_used: 0
          description: OK
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: 0 credits per request.
  /public/v1/accounts/tokens/:
    get:
      operationId: public_v1_accounts_tokens_list
      description: >-
        Returns all API keys for the authenticated user, including inactive
        ones. Each response object includes the raw token value and the `active`
        field indicating current status.
      summary: List API keys
      tags:
        - API Keys
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Token'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: public_v1_accounts_tokens_create
      description: Creates a new API key. The token value is included in the response.
      summary: Create API key
      tags:
        - API Keys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TokenCreateRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/oauth/register/:
    post:
      operationId: public_v1_oauth_register_create
      description: >-
        Open endpoint — no authentication required. Desktop/CLI apps call this
        once to obtain a client_id they persist locally and reuse for all future
        authorize flows.
      summary: Register OAuth client (DCR)
      tags:
        - OAuth
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterClientRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RegisterClientRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RegisterClientRequest'
        required: true
      security: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterClientResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid client metadata
        '401':
          description: Unauthorized — missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/oauth/authorize/:
    get:
      operationId: public_v1_oauth_authorize_list
      description: >-
        OAuth 2.1 authorization endpoint. The client opens the browser at this
        URL; valid requests are redirected to the frontend consent page where
        the user approves access.
      summary: Initiate OAuth authorization
      parameters:
        - in: query
          name: client_id
          schema:
            type: string
          description: The client_id returned during client registration.
          required: true
        - in: query
          name: redirect_uri
          schema:
            type: string
          description: >-
            The URI to redirect to after authorization. Must match one of the
            registered redirect URIs.
          required: true
        - in: query
          name: response_type
          schema:
            type: string
          description: Must be `code`.
          required: true
        - in: query
          name: code_challenge
          schema:
            type: string
          description: >-
            PKCE code challenge. Base64url-encoded SHA-256 hash of the code
            verifier.
          required: true
        - in: query
          name: code_challenge_method
          schema:
            type: string
            default: S256
          description: >-
            PKCE method. Only `S256` is supported. Defaults to `S256` if
            omitted.
          required: false
        - in: query
          name: scope
          schema:
            type: string
            default: ''
          description: >-
            Space-separated list of requested scopes. Available value: `all`.
            Defaults to the full set of scopes granted during registration if
            omitted.
          required: false
        - in: query
          name: state
          schema:
            type: string
            default: ''
          description: >-
            Opaque value to maintain state between the request and the callback.
            Returned unchanged in the redirect.
          required: false
        - in: query
          name: resource
          schema:
            type: string
            default: ''
          description: >-
            RFC 8707 resource indicator — the canonical URI of the API this
            token will be used against. Forwarded through consent and bound to
            the issued token.
          required: false
      tags:
        - OAuth
      security: []
      responses:
        '302':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Redirect to the consent page
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request parameters
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unknown client_id
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/oauth/token/:
    post:
      operationId: public_v1_oauth_token_create
      description: >-
        Accepts `application/x-www-form-urlencoded` or `application/json`.


        **authorization_code grant:** `grant_type`, `code`, `code_verifier`,
        `client_id`, `redirect_uri`


        **refresh_token grant:** `grant_type`, `refresh_token`, `client_id`
      summary: OAuth token endpoint
      tags:
        - OAuth
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TokenRequest'
        required: true
      security: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid grant or request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid client
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/oauth/apps/:
    get:
      operationId: public_v1_oauth_apps_list
      description: Returns all OAuth apps the authenticated user has authorized.
      summary: List connected OAuth apps
      tags:
        - OAuth
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConnectedApp'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/oauth/apps/{app_id}/:
    delete:
      operationId: public_v1_oauth_apps_delete
      description: >-
        Revokes the user's authorization for the given app and deactivates all
        associated access tokens.
      summary: Disconnect OAuth app
      parameters:
        - in: path
          name: app_id
          schema:
            type: integer
          description: >-
            Identifier of the authorization to revoke, as returned in the `id`
            field of the connected apps list.
          required: true
      tags:
        - OAuth
      security:
        - Bearer: []
      responses:
        '204':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Authorization revoked
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: App not found or not authorized by this user
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/accounts/token/:
    get:
      operationId: public_v1_accounts_token_list
      description: Validates the JWT token and retrieves the associated user's info.
      summary: Validate JWT Token
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateJWTToken'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/accounts/tokens/{token_id}/:
    patch:
      operationId: public_v1_accounts_tokens_partial_update
      description: >-
        Update an API key's label, active status, expiration date, or scopes.
        Pass `null` for `expires_at` to remove expiration.
      summary: Update API key
      parameters:
        - in: path
          name: token_id
          schema:
            type: integer
          required: true
      tags:
        - API Keys
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUpdateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenUpdateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TokenUpdateRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Token not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: public_v1_accounts_tokens_delete
      summary: Delete API key
      parameters:
        - in: path
          name: token_id
          schema:
            type: integer
          required: true
      tags:
        - API Keys
      security:
        - Bearer: []
      responses:
        '204':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: API key deleted
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Token not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/discovery/exclusion-lists/:
    get:
      operationId: public_v1_discovery_exclusion_lists_list
      description: >-
        Returns all exclusion lists available to your team, each scoped to a
        single platform. This includes both the auto-created default list per
        platform and any specific lists you have created. Adding handles to a
        list does not filter search on its own — apply a list to a search by
        passing `exclude_list` (list IDs), `exclude_default_list`, or
        `exclude_all_lists` in the Discovery or Similar Creators `filters`.
      summary: List exclusion lists
      tags:
        - Exclusion lists
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: public_v1_discovery_exclusion_lists_create
      description: >-
        Creates a new specific exclusion list for the given platform and returns
        its `id`. Use specific lists for handles you want to apply selectively;
        for a standing, always-on blocklist use the platform's default list
        instead. After creating a list, add handles via
        `/exclusion-lists/{list_id}/entries/`, then apply it to a search by
        passing its ID in `exclude_list` in the Discovery or Similar Creators
        `filters`. This operation is free — it does not consume credits.
      summary: Create exclusion list
      tags:
        - Exclusion lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExclusionListCreateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ExclusionListCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExclusionListCreateRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/discovery/exclusion-lists/default/{platform}/:
    get:
      operationId: public_v1_discovery_exclusion_lists_default_retrieve
      description: >-
        Returns (and auto-creates if needed) the team's default exclusion list
        for the given platform. The default is your standing, always-on
        blocklist, addressed by platform rather than by ID, and cannot be
        deleted. Apply it to a search by passing `exclude_default_list: true` in
        the Discovery or Similar Creators `filters`.
      summary: Get default exclusion list
      parameters:
        - in: path
          name: platform
          schema:
            type: string
            enum:
              - instagram
              - youtube
              - tiktok
              - twitch
              - twitter
              - onlyfans
          description: The social media platform the exclusion list applies to.
          required: true
      tags:
        - Exclusion lists
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid platform
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/discovery/exclusion-lists/default/{platform}/entries/:
    get:
      operationId: public_v1_discovery_exclusion_lists_default_entries_retrieve
      description: >-
        Returns a paginated list of handles in the platform's default exclusion
        list. Defaults to the first 1,000 handles; use `offset` and `limit` to
        page through larger lists. Handles are returned in alphabetical order.
      summary: List handles in the default exclusion list
      parameters:
        - in: path
          name: platform
          schema:
            type: string
            enum:
              - instagram
              - youtube
              - tiktok
              - twitch
              - twitter
              - onlyfans
          description: The social media platform the exclusion list applies to.
          required: true
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Number of handles to skip from the start of the list.
          required: false
        - in: query
          name: limit
          schema:
            type: integer
            default: 1000
            minimum: 1
            maximum: 10000
          description: Maximum number of handles to return (1–10,000).
          required: false
      tags:
        - Exclusion lists
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionEntriesResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid platform
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: public_v1_discovery_exclusion_lists_default_entries_create
      description: >-
        Appends handles to the platform's default exclusion list. Handles are
        normalised automatically (lowercased, @ stripped, full URLs reduced to
        just the handle). Adding handles does not filter search on its own —
        apply the default list to a search by passing `exclude_default_list:
        true` in the Discovery or Similar Creators `filters`. Returns the
        updated list object. This operation is free — it does not consume
        credits.
      summary: Add handles to the default exclusion list
      parameters:
        - in: path
          name: platform
          schema:
            type: string
            enum:
              - instagram
              - youtube
              - tiktok
              - twitch
              - twitter
              - onlyfans
          description: The social media platform the exclusion list applies to.
          required: true
      tags:
        - Exclusion lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: public_v1_discovery_exclusion_lists_default_entries_delete
      description: >-
        Removes handles from the platform's default exclusion list. Returns the
        updated list object. This operation is free — it does not consume
        credits.
      summary: Remove handles from the default exclusion list
      parameters:
        - in: path
          name: platform
          schema:
            type: string
            enum:
              - instagram
              - youtube
              - tiktok
              - twitch
              - twitter
              - onlyfans
          description: The social media platform the exclusion list applies to.
          required: true
      tags:
        - Exclusion lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/discovery/exclusion-lists/{list_id}/:
    get:
      operationId: public_v1_discovery_exclusion_lists_retrieve
      description: Returns a single specific exclusion list by ID.
      summary: Get a specific exclusion list
      parameters:
        - in: path
          name: list_id
          schema:
            type: integer
          description: The exclusion list's unique identifier.
          required: true
      tags:
        - Exclusion lists
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: public_v1_discovery_exclusion_lists_partial_update
      description: >-
        Updates the name of a specific exclusion list. Returns the updated list
        object. This operation is free — it does not consume credits.
      summary: Rename a specific exclusion list
      parameters:
        - in: path
          name: list_id
          schema:
            type: integer
          description: The exclusion list's unique identifier.
          required: true
      tags:
        - Exclusion lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExclusionListUpdateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ExclusionListUpdateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExclusionListUpdateRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: public_v1_discovery_exclusion_lists_delete
      description: >-
        Permanently deletes a specific exclusion list and all its handles. The
        default list for a platform cannot be deleted. This operation is free —
        it does not consume credits.
      summary: Delete a specific exclusion list
      parameters:
        - in: path
          name: list_id
          schema:
            type: integer
          description: The exclusion list's unique identifier.
          required: true
      tags:
        - Exclusion lists
      security:
        - Bearer: []
      responses:
        '204':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Deleted
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/discovery/exclusion-lists/{list_id}/entries/:
    get:
      operationId: public_v1_discovery_exclusion_lists_entries_retrieve
      description: >-
        Returns a paginated list of handles in the specific exclusion list.
        Defaults to the first 1,000 handles; use `offset` and `limit` to page
        through larger lists. Handles are returned in alphabetical order.
      summary: List handles in a specific exclusion list
      parameters:
        - in: path
          name: list_id
          schema:
            type: integer
          description: The exclusion list's unique identifier.
          required: true
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Number of handles to skip from the start of the list.
          required: false
        - in: query
          name: limit
          schema:
            type: integer
            default: 1000
            minimum: 1
            maximum: 10000
          description: Maximum number of handles to return (1–10,000).
          required: false
      tags:
        - Exclusion lists
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionEntriesResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: public_v1_discovery_exclusion_lists_entries_create
      description: >-
        Appends handles to the specific exclusion list. Handles are normalised
        automatically (lowercased, @ stripped, full URLs reduced to just the
        handle). Adding handles does not filter search on its own — apply the
        list to a search by passing its ID in `exclude_list` in the Discovery or
        Similar Creators `filters`. Returns the updated list object. This
        operation is free — it does not consume credits.
      summary: Add handles to a specific exclusion list
      parameters:
        - in: path
          name: list_id
          schema:
            type: integer
          description: The exclusion list's unique identifier.
          required: true
      tags:
        - Exclusion lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: public_v1_discovery_exclusion_lists_entries_delete
      description: >-
        Removes handles from the specific exclusion list. Returns the updated
        list object. This operation is free — it does not consume credits.
      summary: Remove handles from a specific exclusion list
      parameters:
        - in: path
          name: list_id
          schema:
            type: integer
          description: The exclusion list's unique identifier.
          required: true
      tags:
        - Exclusion lists
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExclusionEntriesInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExclusionList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /public/v1/social/listening/subscription/:
    get:
      operationId: public_v1_social_listening_subscription_list
      description: >-
        Return a paginated list of the client's social-listening subscriptions,
        optionally filtered by type. The response includes a `summary` block
        with aggregate counts. Monitoring is billed per creator, per day — API
        calls are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: List subscriptions
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: Page number (1-based) for the paginated result.
          required: false
        - in: query
          name: page_size
          schema:
            type: integer
          description: Number of results to return per page. Defaults to 10.
          required: false
      tags:
        - Subscriptions
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    post:
      operationId: public_v1_social_listening_subscription_create
      description: >-
        Create a new social-listening subscription from handles and/or discovery
        lists. Monitoring is billed per creator, per day — API calls are
        included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Create subscription
      tags:
        - Subscriptions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error or limit exceeded
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/subscription/{subscription_id}/:
    get:
      operationId: public_v1_social_listening_subscription_retrieve
      description: >-
        Return the full detail representation of a subscription, including
        creators, daily cost, and (for campaign subscriptions) stats. Monitoring
        is billed per creator, per day — API calls are included in that price.
        See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Get subscription
      parameters:
        - in: path
          name: subscription_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Subscriptions
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Subscription not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    patch:
      operationId: public_v1_social_listening_subscription_partial_update
      description: >-
        Partially update a subscription (name, endpoints, or creators). Status
        changes (pause/resume) on campaign-backed subscriptions are rejected;
        their lifecycle is driven by the campaign. Monitoring is billed per
        creator, per day — API calls are included in that price. See [Usage,
        pricing & limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Update subscription
      parameters:
        - in: path
          name: subscription_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Subscriptions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error, insufficient credits, or campaign-managed
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Subscription not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    delete:
      operationId: public_v1_social_listening_subscription_delete
      description: >-
        Delete a webhook subscription and all its related links. Campaign-backed
        subscriptions are rejected; archive the campaign instead (`DELETE
        /campaign/<pk>/`). Monitoring is billed per creator, per day — API calls
        are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Delete subscription
      parameters:
        - in: path
          name: subscription_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Subscriptions
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Subscription deleted
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign-managed subscription
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Subscription not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/subscription/{subscription_id}/creators/:
    get:
      operationId: public_v1_social_listening_subscription_creators_retrieve
      description: >-
        Return a paginated list of creators in the subscription with follower
        and source metadata, optionally filtered by handle via the `search`
        query parameter. Monitoring is billed per creator, per day — API calls
        are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: List subscription creators
      parameters:
        - in: path
          name: subscription_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
        - in: query
          name: page
          schema:
            type: integer
          description: Page number (1-based) for the paginated result.
          required: false
        - in: query
          name: search
          schema:
            type: string
          description: Filter creators by handle (case-insensitive substring match).
          required: false
        - in: query
          name: page_size
          schema:
            type: integer
            default: 10
          description: Number of results to return per page. Defaults to 10.
          required: false
      tags:
        - Subscriptions
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCreatorListPage'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Subscription not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    post:
      operationId: public_v1_social_listening_subscription_creators_create
      description: >-
        Add creators to the subscription from handles, discovery lists, and/or a
        CSV file (a `handle` column is required). Monitoring is billed per
        creator, per day — API calls are included in that price. See [Usage,
        pricing & limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Add subscription creators
      parameters:
        - in: path
          name: subscription_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Subscriptions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSubscriptionCreatorsInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AddSubscriptionCreatorsInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AddSubscriptionCreatorsInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Creators added
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error or insufficient credits
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Subscription not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/subscription/{subscription_id}/details/:
    get:
      operationId: public_v1_social_listening_subscription_details_retrieve
      description: >-
        Return aggregated delivery stats for a campaign subscription. Monitoring
        is billed per creator, per day — API calls are included in that price.
        See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Get subscription stats
      parameters:
        - in: path
          name: subscription_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Subscriptions
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Stats counters
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Subscription not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/subscription/{subscription_id}/details/export/:
    get:
      operationId: public_v1_social_listening_subscription_details_export_retrieve
      description: >-
        Download the campaign subscription's aggregated stats as a CSV file.
        Monitoring is billed per creator, per day — API calls are included in
        that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Export subscription stats (CSV)
      parameters:
        - in: path
          name: subscription_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Subscriptions
      security:
        - Bearer: []
      responses:
        '200':
          content:
            text/csv:
              schema:
                type: string
                format: binary
          description: CSV file download
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Subscription not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/campaign/:
    get:
      operationId: public_v1_social_listening_campaign_list
      description: >-
        Return a paginated list of the client's campaigns, optionally filtered
        by status and search, with a `status_counts` summary. Monitoring is
        billed per creator, per day — API calls are included in that price. See
        [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: List campaigns
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: Page number (1-based) for the paginated result.
          required: false
        - in: query
          name: status
          schema:
            type: string
          description: Filter campaigns by lifecycle status. Omit to return all statuses.
          required: false
        - in: query
          name: search
          schema:
            type: string
          description: Filter campaigns by name (case-insensitive substring match).
          required: false
        - in: query
          name: ordering
          schema:
            type: string
            default: '-created_at'
          description: >-
            Sort field; prefix with '-' for descending. Defaults to newest first
            ('-created_at').
          required: false
        - in: query
          name: page_size
          schema:
            type: integer
            default: 10
          description: Number of results to return per page. Defaults to 10.
          required: false
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignListPage'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    post:
      operationId: public_v1_social_listening_campaign_create
      description: >-
        Create a campaign and its backing per-platform webhook subscriptions.
        Monitoring is billed per creator, per day — API calls are included in
        that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Create campaign
      tags:
        - Campaigns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCampaignInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateCampaignInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateCampaignInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/campaign/{campaign_id}/:
    get:
      operationId: public_v1_social_listening_campaign_retrieve
      description: >-
        Return the detail representation of a single campaign by id. Team
        members can view campaigns within their client scope. Monitoring is
        billed per creator, per day — API calls are included in that price. See
        [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Get campaign
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponse'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    patch:
      operationId: public_v1_social_listening_campaign_partial_update
      description: >-
        Update a campaign's status, budget and/or content types. Setting
        `status` to `paused` or `active` pauses/resumes the campaign and
        cascades the same status to all its backing subscriptions; resuming runs
        a credit check. Editing content types re-derives and propagates the
        detection filters to the campaign's backing subscriptions. Archived or
        completed campaigns cannot be edited. Monitoring is billed per creator,
        per day — API calls are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Update campaign
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Campaigns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCampaignInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateCampaignInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpdateCampaignInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Validation error, insufficient credits, or non-editable campaign
            status
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    delete:
      operationId: public_v1_social_listening_campaign_delete
      description: >-
        Archive a campaign and disable all its backing subscriptions. This is a
        soft delete: rows are retained but detection is stopped. Monitoring is
        billed per creator, per day — API calls are included in that price. See
        [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Archive campaign
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Campaign archived
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/campaign/{campaign_id}/creators/:
    get:
      operationId: public_v1_social_listening_campaign_creators_retrieve
      description: >-
        Return a paginated list of the campaign's creators with per-creator
        metrics (posts, views, engagement, ER%, EMV, and a 7-day trend),
        searchable by handle/name and sortable by any metric column. Creators
        added but not yet posting are included with status
        `awaiting_first_post`. Monitoring is billed per creator, per day — API
        calls are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: List campaign creators
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
        - in: query
          name: page
          schema:
            type: integer
          description: Page number (1-based) for the paginated result.
          required: false
        - in: query
          name: platform
          schema:
            type: string
          description: The creator's social media platform.
          required: false
        - in: query
          name: search
          schema:
            type: string
          description: >-
            Filter creators by handle or display name (case-insensitive
            substring match).
          required: false
        - in: query
          name: ordering
          schema:
            type: string
            default: added_at
          description: >-
            Sort field; prefix with '-' for descending. Defaults to attachment
            order ('added_at').
          required: false
        - in: query
          name: page_size
          schema:
            type: integer
            default: 10
          description: Number of results to return per page. Defaults to 10.
          required: false
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignCreatorListPage'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    post:
      operationId: public_v1_social_listening_campaign_creators_create
      description: >-
        Add creators to one of the campaign's platforms from handles, a
        discovery list, and/or a CSV file. Monitoring is billed per creator, per
        day — API calls are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Add campaign creators
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Campaigns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCampaignCreatorsInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AddCampaignCreatorsInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AddCampaignCreatorsInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Creators added
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error or insufficient credits
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    delete:
      operationId: public_v1_social_listening_campaign_creators_delete
      description: >-
        Remove creators from the campaign by creator id (the `id` field from the
        Creators list). The creators' links are deleted while the campaign and
        subscriptions are kept; detection stops for the removed creators.
        Idempotent: ids that aren't on the campaign are ignored. Monitoring is
        billed per creator, per day — API calls are included in that price. See
        [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Remove campaign creators
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Campaigns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveCampaignCreatorsInputRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RemoveCampaignCreatorsInputRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RemoveCampaignCreatorsInputRequest'
        required: true
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Creators removed
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/campaign/{campaign_id}/overview/:
    get:
      operationId: public_v1_social_listening_campaign_overview_retrieve
      description: >-
        Return the aggregated overview metrics for a single campaign, including
        total posts, views, engagement, EMV, and trends. Optionally filter by
        platform using the `platform` query parameter. Monitoring is billed per
        creator, per day — API calls are included in that price. See [Usage,
        pricing & limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Get campaign overview
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
        - in: query
          name: platform
          schema:
            type: string
          description: The creator's social media platform.
          required: false
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Campaign overview metrics
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/campaign/{campaign_id}/content/:
    get:
      operationId: public_v1_social_listening_campaign_content_retrieve
      description: >-
        Return a paginated feed of the campaign's posts (one per detected
        `new_post` event), optionally narrowed to a single platform and sorted
        by a metric column (defaults to most recent first). Each post carries
        its creator, metrics, per-post EMV and ER%, media, and a `top` flag for
        the highest-ER posts. Monitoring is billed per creator, per day — API
        calls are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: List campaign content
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
        - in: query
          name: page
          schema:
            type: integer
          description: Page number (1-based) for the paginated result.
          required: false
        - in: query
          name: platform
          schema:
            type: string
          description: The creator's social media platform.
          required: false
        - in: query
          name: ordering
          schema:
            type: string
            default: '-posted_at'
          description: >-
            Sort field; prefix with '-' for descending. Defaults to most recent
            first ('-posted_at').
          required: false
        - in: query
          name: page_size
          schema:
            type: integer
            default: 10
          description: Number of results to return per page. Defaults to 10.
          required: false
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignContentListPage'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/campaign/{campaign_id}/report/:
    get:
      operationId: public_v1_social_listening_campaign_report_retrieve
      description: >-
        Return the campaign's most recent AI report. While the report is being
        generated its `status` is `generating` and `report_data` is empty — poll
        until `status` becomes `ready` (or `failed`). Monitoring is billed per
        creator, per day — API calls are included in that price. See [Usage,
        pricing & limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Get campaign AI report
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignReport'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found, or no report generated yet
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
    post:
      operationId: public_v1_social_listening_campaign_report_create
      description: >-
        Start asynchronous generation of a new AI report for the campaign (also
        used to regenerate). Returns the pending report; poll the GET endpoint
        until its `status` is `ready`. If a generation is already in progress
        the pending report is returned instead of starting another one.
        Monitoring is billed per creator, per day — API calls are included in
        that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Generate campaign AI report
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignReport'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign has not started yet
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/campaign/{campaign_id}/report/export/:
    get:
      operationId: public_v1_social_listening_campaign_report_export_retrieve
      description: >-
        Download the campaign's raw post-level report data as a CSV file (one
        row per detected post with its metrics). Monitoring is billed per
        creator, per day — API calls are included in that price. See [Usage,
        pricing & limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Export campaign report data (CSV)
      parameters:
        - in: path
          name: campaign_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Campaigns
      security:
        - Bearer: []
      responses:
        '200':
          content:
            text/csv:
              schema:
                type: string
                format: binary
          description: CSV file download
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Campaign not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/events/:
    get:
      operationId: public_v1_social_listening_events_list
      description: >-
        Return a paginated list of the client's events, optionally filtered by
        subscription, event type, or creator. Monitoring is billed per creator,
        per day — API calls are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: List events
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: Page number (1-based) for the paginated result.
          required: false
        - in: query
          name: subscription_id
          schema:
            type: integer
          description: Return only events belonging to this subscription.
          required: false
        - in: query
          name: event_type
          schema:
            type: string
          description: Filter events by type (e.g. 'new_post', 'bio_change').
          required: false
        - in: query
          name: creator
          schema:
            type: string
          description: Filter events by creator handle (exact match).
          required: false
        - in: query
          name: page_size
          schema:
            type: integer
            default: 10
          description: Number of results to return per page. Defaults to 10.
          required: false
      tags:
        - Events
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListPage'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/events/{event_id}/:
    get:
      operationId: public_v1_social_listening_events_retrieve
      description: >-
        Return a single event with its full payload and delivery history.
        Monitoring is billed per creator, per day — API calls are included in
        that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Get event
      parameters:
        - in: path
          name: event_id
          schema:
            type: integer
          description: Unique identifier for the resource
          required: true
      tags:
        - Events
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDetail'
          description: ''
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Event not found
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
  /public/v1/social/listening/usage/:
    get:
      operationId: public_v1_social_listening_usage_list
      description: >-
        Return current social-listening limits and active subscription counts
        for the client's scope. Monitoring is billed per creator, per day — API
        calls are included in that price. See [Usage, pricing &
        limits](guides/usage-limits.md#social-listening-monitoring).
      summary: Get usage
      tags:
        - Usage
      security:
        - Bearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: Usage and limits
        '400':
          description: Bad request — invalid input or unsupported state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
        '403':
          description: Forbidden — caller is not permitted to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity — validation failed.
        '429':
          description: >-
            Too Many Requests — rate or capacity limit exceeded. Inspect the
            `Retry-After` header and the `retry_after` body field for the wait
            time in seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-credits: >-
        Monitoring is billed per creator, per day — API calls are included in
        that price. See the Usage, pricing and limits guide.
components:
  schemas:
    AccountCreditsUsageResponse:
      type: object
      x-expandLevel: 2
      properties:
        credits_available:
          type: number
          description: Remaining credits available for the account.
        credits_used:
          type: number
          description: Credits used by the account.
      required:
        - credits_available
        - credits_used
    AccountProfile:
      type: object
      properties:
        full_name:
          type: string
        username:
          type: string
          description: The creator's username on the platform.
        picture:
          type: string
          format: uri
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
        followers:
          type: integer
        engagement_percent:
          type: number
          format: double
      required:
        - full_name
        - username
        - picture
        - followers
        - engagement_percent
    AccountResponse:
      type: object
      properties:
        user_id:
          type: string
          description: The creator's unique platform identifier.
        profile:
          $ref: '#/components/schemas/AccountProfile'
        similarity_score:
          type: number
          format: double
          description: >-
            How closely this creator matches your reference. Higher values
            indicate a stronger match.
        matched_filters:
          $ref: '#/components/schemas/MatchedFilters'
          description: Only present when return_filter_values=true.
      required:
        - user_id
        - profile
    AddCampaignCreatorsInput:
      type: object
      properties:
        platform:
          type: string
          description: >-
            Platform to add the creators under. Must be one of the campaign's
            platforms.
        handles:
          type: array
          items:
            type: string
          description: >-
            Creator handles to add. Provide at least one of handles, list_ids,
            or csv_file.
        list_ids:
          type: array
          items:
            type: integer
          description: >-
            IDs of discovery lists whose creators are added. Each list's
            platform must match.
        csv_file:
          type: string
          format: binary
          description: CSV upload of creator handles (see handle_column).
        handle_column:
          type: string
          description: >-
            Name of the CSV column holding creator handles. Matched
            case-insensitively; defaults to 'handle'.
          default: handle
      required:
        - platform
    AddCampaignCreatorsInputRequest:
      type: object
      properties:
        platform:
          type: string
          description: >-
            Platform to add the creators under. Must be one of the campaign's
            platforms.
        handles:
          type: array
          items:
            type: string
          description: >-
            Creator handles to add. Provide at least one of handles, list_ids,
            or csv_file.
        list_ids:
          type: array
          items:
            type: integer
          description: >-
            IDs of discovery lists whose creators are added. Each list's
            platform must match.
        csv_file:
          type: string
          format: binary
          description: CSV upload of creator handles (see handle_column).
        handle_column:
          type: string
          description: >-
            Name of the CSV column holding creator handles. Matched
            case-insensitively; defaults to 'handle'.
          default: handle
      required:
        - platform
    AddSubscriptionCreatorsInput:
      type: object
      properties:
        handles:
          type: array
          items:
            type: string
          description: >-
            Creator handles to add. Provide at least one of handles, list_ids,
            or csv_file.
        list_ids:
          type: array
          items:
            type: integer
          description: >-
            Discovery list IDs whose creators are added. Each list's platform
            must match the subscription's platform.
        csv_file:
          type: string
          format: binary
          description: CSV upload of creator handles (see handle_column).
        handle_column:
          type: string
          description: >-
            Name of the CSV column holding creator handles. Matched
            case-insensitively; defaults to 'handle'.
          default: handle
    AddSubscriptionCreatorsInputRequest:
      type: object
      properties:
        handles:
          type: array
          items:
            type: string
          description: >-
            Creator handles to add. Provide at least one of handles, list_ids,
            or csv_file.
        list_ids:
          type: array
          items:
            type: integer
          description: >-
            Discovery list IDs whose creators are added. Each list's platform
            must match the subscription's platform.
        csv_file:
          type: string
          format: binary
          description: CSV upload of creator handles (see handle_column).
        handle_column:
          type: string
          description: >-
            Name of the CSV column holding creator handles. Matched
            case-insensitively; defaults to 'handle'.
          default: handle
    AudienceAge:
      type: object
      properties:
        range:
          type: string
          enum:
            - 13-17
            - 18-24
            - 25-34
            - 35-44
            - 45-64
            - 65-
            - 65+
          nullable: true
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceAgeFilterRequest:
      type: object
      properties:
        range:
          type: string
          enum:
            - 13-17
            - 18-24
            - 25-34
            - 35-44
            - 45-64
            - 65-
            - 65+
          nullable: true
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceDataResponse:
      type: object
      description: >-
        Audience insights returned when include_audience_data is enabled.
        Contains demographic breakdowns for followers, commenters, and likers.
      properties:
        audience_followers:
          type: object
          nullable: true
          description: >-
            Demographic breakdown of the creator's followers. Includes geo,
            languages, ages, genders, interests, brand affinities, credibility
            score, and reachability.
          additionalProperties: true
        audience_commenters:
          type: object
          nullable: true
          description: >-
            Demographic breakdown of the creator's commenters. Same structure as
            audience_followers.
          additionalProperties: true
        audience_likers:
          type: object
          nullable: true
          description: >-
            Demographic breakdown of the creator's likers. Includes credibility
            score and credibility class.
          additionalProperties: true
        audience_credibility_followers_histogram:
          type: array
          nullable: true
          description: Distribution of follower credibility scores as a histogram.
          items:
            type: object
            additionalProperties: true
        audience_credibility_likers_histogram:
          type: array
          nullable: true
          description: Distribution of liker credibility scores as a histogram.
          items:
            type: object
            additionalProperties: true
    AudienceFilterRequest:
      type: object
      properties:
        location:
          type: array
          items:
            $ref: '#/components/schemas/AudienceLocationFilterRequest'
          nullable: true
        gender:
          allOf:
            - $ref: '#/components/schemas/AudienceGenderFilterRequest'
          nullable: true
        language:
          type: array
          items:
            $ref: '#/components/schemas/AudienceLanguageFilterRequest'
          nullable: true
        age:
          type: array
          items:
            $ref: '#/components/schemas/AudienceAgeFilterRequest'
          nullable: true
        interests:
          type: array
          items:
            $ref: '#/components/schemas/AudienceInterestFilterRequest'
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        brand_categories:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        credibility:
          type: string
          enum:
            - bad
            - low
            - normal
            - good
            - high
            - best
          nullable: true
    AudienceGender:
      type: object
      properties:
        type:
          type: string
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceGenderFilterRequest:
      type: object
      properties:
        type:
          type: string
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceInterest:
      type: object
      properties:
        name:
          type: string
          nullable: true
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceInterestFilterRequest:
      type: object
      properties:
        name:
          type: string
          nullable: true
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceLanguage:
      type: object
      properties:
        language_abbr:
          type: string
          nullable: true
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceLanguageFilterRequest:
      type: object
      properties:
        language_abbr:
          type: string
          nullable: true
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceLocation:
      type: object
      properties:
        name:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - country
            - state
            - city
          nullable: true
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceLocationFilterRequest:
      type: object
      properties:
        name:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - country
            - state
            - city
          nullable: true
        min_pct:
          type: number
          format: double
          nullable: true
    AudienceOverlapInput:
      type: object
      properties:
        platform:
          type: string
        creators:
          type: array
          items:
            type: string
      required:
        - platform
        - creators
      example:
        platform: instagram
        creators:
          - creator_handle_1
          - creator_handle_2
    AudienceOverlapResponse:
      type: object
      properties:
        credits_cost:
          type: number
          format: double
          nullable: true
          example: 1
        credits_left:
          type: number
          format: double
          nullable: true
        status:
          type: boolean
          nullable: true
        success:
          type: boolean
          nullable: true
        basics:
          allOf:
            - $ref: '#/components/schemas/ReportInfo'
          nullable: true
        details:
          type: array
          items:
            $ref: '#/components/schemas/OverlapDataItem'
    BatchEnrichmentDownloadURL:
      type: object
      properties:
        download_url:
          type: string
          format: uri
          description: Temporary presigned S3 download URL
        filename:
          type: string
          description: Suggested filename for the download
        expires_in:
          type: integer
          description: URL expiration time in seconds
        expires_at:
          type: string
          description: ISO 8601 timestamp when the URL expires
        batch_id:
          type: string
          description: Unique identifier for the batch enrichment job
        total_results:
          type: integer
          description: Number of enriched results in the file
        invalid_records:
          type: integer
          description: Number of invalid records in the batch
      required:
        - download_url
        - filename
        - expires_in
        - expires_at
        - batch_id
        - total_results
        - invalid_records
    BatchEnrichmentInput:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: >-
            CSV file containing creators to enrich (max 10MB, single column:
            handle or email)
        platform:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - twitter
            - twitch
            - onlyfans
          description: Social media platform (required for handle-based enrichment)
        enrichment_mode:
          type: string
          enum:
            - raw
            - full
            - basic
          description: >-
            Enrichment mode: 'raw' or 'full' for handle-based, 'basic' or
            'advanced' for email-based
        metadata:
          type: object
          description: 'Optional metadata as JSON object (e.g., {"campaign": "Q4 Outreach"})'
          nullable: true
          additionalProperties: {}
        email_required:
          type: string
          enum:
            - must_have
            - preferred
          description: >-
            Email requirement for handle-based full enrichment. Default:
            "preferred"
        include_lookalikes:
          type: boolean
          description: >-
            Include lookalike creators for handle-based full enrichment.
            Default: false
          default: false
        include_audience_data:
          type: boolean
          description: >-
            Include audience data for handle-based full enrichment. Default:
            true
          default: true
        exclude_platforms:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - twitter
            - twitch
            - onlyfans
          description: Platforms to exclude from response
        min_followers:
          type: integer
      required:
        - file
        - enrichment_mode
      example:
        file: (binary)
        platform: instagram
        enrichment_mode: full
        metadata:
          campaign: Q4 Outreach
        email_required: preferred
        include_lookalikes: false
        include_audience_data: true
        exclude_platforms: twitter
        min_followers: 1000
    BatchEnrichmentInputRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: >-
            CSV file containing creators to enrich (max 10MB, single column:
            handle or email)
        platform:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - twitter
            - twitch
            - onlyfans
          description: Social media platform (required for handle-based enrichment)
        enrichment_mode:
          type: string
          enum:
            - raw
            - full
            - basic
          description: >-
            Enrichment mode: 'raw' or 'full' for handle-based, 'basic' or
            'advanced' for email-based
        metadata:
          type: object
          description: 'Optional metadata as JSON object (e.g., {"campaign": "Q4 Outreach"})'
          nullable: true
          additionalProperties: {}
        email_required:
          type: string
          enum:
            - must_have
            - preferred
          description: >-
            Email requirement for handle-based full enrichment. Default:
            "preferred"
        include_lookalikes:
          type: boolean
          description: >-
            Include lookalike creators for handle-based full enrichment.
            Default: false
          default: false
        include_audience_data:
          type: boolean
          description: >-
            Include audience data for handle-based full enrichment. Default:
            true
          default: true
        exclude_platforms:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - twitter
            - twitch
            - onlyfans
          description: Platforms to exclude from response
        min_followers:
          type: integer
      required:
        - file
        - enrichment_mode
      example:
        file: (binary)
        platform: instagram
        enrichment_mode: full
        metadata:
          campaign: Q4 Outreach
        email_required: preferred
        include_lookalikes: false
        include_audience_data: true
        exclude_platforms: twitter
        min_followers: 1000
    BatchEnrichmentResponse:
      type: object
      properties:
        batch_id:
          type: string
          description: Unique identifier for the batch enrichment job
        status:
          type: string
          description: >-
            Current status of the batch job (processing, finished, failed,
            validating)
        created_at:
          type: string
          format: date-time
          description: Timestamp when the batch was created
        platform:
          type: string
          description: Platform used for enrichment (for handle-based enrichment)
          nullable: true
        metadata:
          type: object
          description: Metadata provided with the batch
          nullable: true
          additionalProperties: {}
        og_input_number:
          type: integer
          description: Total number of records in the input file
        type_report:
          type: string
          description: 'Type of enrichment: ENRICH_BY_HANDLE or ENRICH_BY_EMAIL'
        enrichment_mode:
          type: string
          description: 'Enrichment mode: raw, full, basic'
          nullable: true
        message:
          type: string
          description: Human-readable message about the batch status
      required:
        - batch_id
        - status
        - created_at
        - og_input_number
        - type_report
        - message
      x-expandLevel: 2
    BatchEnrichmentStatusResponse:
      type: object
      properties:
        batch_id:
          type: string
          description: Unique identifier for the batch enrichment job
        status:
          type: string
          description: >-
            Current status of the batch job (processing, finished, failed,
            queued, paused_insufficient_credits)
        total_rows:
          type: integer
          description: Total number of records submitted in the batch
        processed_rows:
          type: integer
          description: Total number of records that have finished processing
        success_count:
          type: integer
          description: Number of records processed successfully
        failed_count:
          type: integer
          description: Number of records that failed or could not be processed
        started_at:
          type: string
          format: date-time
          description: Timestamp when the batch was created
        metadata:
          type: object
          description: Metadata provided with the batch
          additionalProperties: {}
        credits_used:
          type: string
          format: decimal
          description: Total number of credits used in the batch
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        estimated_completion:
          type: string
          format: date-time
          description: >-
            Estimated completion timestamp based on current progress (null if
            unavailable)
          nullable: true
        status_message:
          type: string
          description: >-
            Human-readable message about the batch status (only present when
            paused)
          nullable: true
      required:
        - batch_id
        - status
        - total_rows
        - processed_rows
        - success_count
        - failed_count
        - started_at
        - metadata
        - credits_used
      x-expandLevel: 2
    Brand:
      type: object
      properties:
        full_name:
          type: string
          description: Display name, e.g. "L'Oréal Professionnel Paris".
        cleaned:
          type: string
          description: >-
            Normalised name, without accents, punctuation or emoji and often
            shorter than the display name, e.g. "Loreal". This is what
            `exact=false` searches.
        username:
          type: string
          description: The value to use in the `brands` filter on the Discovery API.
      required:
        - full_name
        - cleaned
        - username
    BrandAffinityResponse:
      type: object
      properties:
        name:
          type: string
          description: Name of the brand.
          nullable: true
        interest:
          type: array
          items:
            type: string
          description: Interest categories associated with the brand.
    CampaignContent:
      type: object
      properties:
        platform:
          type: string
          description: Platform the post was published on.
        post_type:
          type: string
          description: Display post type (e.g. 'post', 'reel', 'video', 'story').
        creator:
          $ref: '#/components/schemas/CampaignContentCreator'
          description: The post's creator.
        caption:
          type: string
          description: Post caption; empty string when unavailable.
        url:
          type: string
          description: Permalink to the post; empty string when unavailable.
        media:
          type: object
          description: >-
            Normalized media payload (cover image, video URL, etc.); shape
            varies by platform, null when unavailable.
          nullable: true
          additionalProperties: {}
        posted_at:
          type: string
          description: >-
            Post timestamp: the post's own taken_at (a unix timestamp or ISO
            8601 string) when present, else the detection time (ISO 8601).
        metrics_live:
          type: boolean
          description: >-
            True when the metrics come from the creator's latest scrape (post
            still in the recent-posts window); false when they are the stored
            values, refreshed daily for active campaigns.
        metrics_note:
          type: string
          description: Explanation of the metrics source when not live; null when live.
          nullable: true
        post_unavailable:
          type: boolean
          description: >-
            True when the post was found deleted/unavailable at rescrape; the
            metrics shown are the last values captured before removal.
        last_metrics_update:
          type: string
          format: date-time
          description: When the post's metrics were last captured (ISO 8601).
        views:
          type: integer
          description: View count, or null when unavailable.
          nullable: true
        likes:
          type: integer
          description: Like count, or null when unavailable.
          nullable: true
        comments:
          type: integer
          description: Comment count, or null when unavailable.
          nullable: true
        engagement:
          type: integer
          description: Likes + comments, or null when unavailable.
          nullable: true
        er:
          type: number
          format: double
          description: Engagement rate as a percentage, or null when unavailable.
          nullable: true
        emv:
          type: integer
          description: >-
            Earned Media Value for the post, rounded to the nearest 100, or null
            when unavailable.
          nullable: true
        is_top:
          type: boolean
          description: True when the post ranks in the top 10% by engagement rate.
      required:
        - platform
        - post_type
        - creator
        - posted_at
        - metrics_live
        - post_unavailable
        - last_metrics_update
        - is_top
    CampaignContentCreator:
      type: object
      properties:
        handle:
          type: string
          description: The creator's handle on the platform.
        name:
          type: string
          description: The creator's display name.
        avatar:
          type: string
          format: uri
          description: Signed profile-picture URL, or null.
          nullable: true
      required:
        - handle
        - name
    CampaignContentListPage:
      type: object
      properties:
        count:
          type: integer
          description: Total number of posts matching the filter.
        next:
          type: string
          format: uri
          description: URL of the next page, or null on the last page.
          nullable: true
        previous:
          type: string
          format: uri
          description: URL of the previous page, or null on the first page.
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/CampaignContent'
          description: Posts on the current page.
      required:
        - count
        - results
    CampaignCreator:
      type: object
      properties:
        id:
          type: integer
          description: Creator link identifier.
        platform:
          type: string
          description: The creator's platform for this campaign.
        handle:
          type: string
          description: The creator's handle on the platform.
        name:
          type: string
          description: The creator's display name.
        avatar:
          type: string
          format: uri
          description: Signed profile-picture URL, or null.
          nullable: true
        posts:
          type: integer
          description: Campaign posts detected for the creator.
        views:
          type: integer
          description: Blended impressions estimate summed across the creator's posts.
        engagement:
          type: integer
          description: Total engagement (likes + comments) across the creator's posts.
        er:
          type: number
          format: double
          description: >-
            Average engagement rate as a percentage, or null when the follower
            count is unknown.
          nullable: true
        emv:
          type: integer
          description: Earned Media Value for the creator, rounded to the nearest 100.
        trend:
          type: array
          items:
            $ref: '#/components/schemas/CampaignCreatorTrendPoint'
          description: Daily engagement/post trend for the last 7 days.
        status:
          type: string
          enum:
            - posting
            - awaiting_first_post
          description: >-
            'posting' once the creator has campaign posts; 'awaiting_first_post'
            if added but not yet posting.
        added_at:
          type: string
          format: date-time
          description: When the creator was added to the campaign.
      required:
        - id
        - platform
        - handle
        - name
        - posts
        - views
        - engagement
        - emv
        - trend
        - status
        - added_at
    CampaignCreatorListPage:
      type: object
      properties:
        count:
          type: integer
          description: Total number of creators matching the filter.
        next:
          type: string
          format: uri
          description: URL of the next page, or null on the last page.
          nullable: true
        previous:
          type: string
          format: uri
          description: URL of the previous page, or null on the first page.
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/CampaignCreator'
          description: Creators on the current page.
      required:
        - count
        - results
    CampaignCreatorTrendPoint:
      type: object
      properties:
        date:
          type: string
          format: date
          description: Calendar day (ISO 8601) in the account timezone.
        engagement:
          type: integer
          description: Likes + comments detected that day.
        posts:
          type: integer
          description: Posts detected that day.
      required:
        - date
        - engagement
        - posts
    CampaignListPage:
      type: object
      properties:
        count:
          type: integer
          description: Total number of campaigns matching the filter.
        next:
          type: string
          format: uri
          description: URL of the next page, or null on the last page.
          nullable: true
        previous:
          type: string
          format: uri
          description: URL of the previous page, or null on the first page.
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/CampaignListResponse'
          description: Campaigns on the current page.
        status_counts:
          $ref: '#/components/schemas/CampaignStatusCounts'
          description: >-
            Counts of the client's campaigns by status. Computed across all
            campaigns in scope, ignoring the status filter.
      required:
        - count
        - results
        - status_counts
    CampaignListResponse:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        platforms:
          type: object
          additionalProperties: {}
        status:
          type: string
        content_types:
          type: object
          nullable: true
          additionalProperties: {}
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        budget:
          type: string
          format: decimal
          nullable: true
        creator_count:
          type: string
          description: Number of creators tracked across the campaign's subscriptions.
        sample_creators:
          type: string
          description: >-
            Up to 5 sampled creators (handle + avatar) across the campaign's
            subscriptions.
        total_posts:
          type: string
          description: Total detected posts summed across the campaign's subscriptions.
        engagement:
          type: string
          description: >-
            Total engagement (likes + comments) across the campaign's
            subscriptions.
        emv:
          type: string
          description: >-
            Earned Media Value for the campaign, computed per-platform and
            summed.
        seven_day_trend:
          type: string
          description: Daily engagement/post trend for the last 7 days.
        created_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - platforms
        - status
        - start_date
        - end_date
        - created_at
    CampaignReport:
      type: object
      properties:
        id:
          type: integer
        status:
          type: string
          description: 'Generation status: ''generating'', ''ready'', or ''failed''.'
        report_data:
          type: object
          description: >-
            Structured report content the dashboard renders; empty until status
            is 'ready'.
          additionalProperties: {}
        model_used:
          type: string
          description: Identifier of the AI model that generated the report.
        error_message:
          type: string
          description: Error detail when status is 'failed'; empty otherwise.
        generated_at:
          type: string
          format: date-time
          description: When generation completed; null until the report is ready.
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - status
        - created_at
        - updated_at
    CampaignResponse:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        platforms:
          type: object
          additionalProperties: {}
        status:
          type: string
        brief:
          type: string
        content_types:
          type: object
          nullable: true
          additionalProperties: {}
        tracking_keywords:
          type: object
          nullable: true
          additionalProperties: {}
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        budget:
          type: string
          format: decimal
          nullable: true
        creator_count:
          type: string
          description: Number of live creator links across the campaign's subscriptions.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - platforms
        - status
        - start_date
        - end_date
        - created_at
        - updated_at
    CampaignStatusCounts:
      type: object
      properties:
        draft:
          type: integer
          description: Number of draft campaigns.
        active:
          type: integer
          description: Number of active campaigns.
        paused:
          type: integer
          description: Number of paused campaigns.
        completed:
          type: integer
          description: Number of completed campaigns.
      required:
        - draft
        - active
        - paused
        - completed
    ConnectedApp:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier of the authorization, used to disconnect the app.
        name:
          type: string
          description: Display name of the connected application.
        client_id:
          type: string
          description: OAuth client_id of the connected application.
        granted_scopes:
          type: array
          items:
            type: string
          description: Scopes the user granted to this application.
        created_at:
          type: string
          format: date-time
          description: When the application was first authorized.
      required:
        - id
        - name
        - client_id
        - granted_scopes
        - created_at
    ConnectedSocial:
      type: object
      properties:
        platform:
          type: string
          description: The creator's social media platform.
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        url:
          type: string
          description: The creator's profile URL.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        fullname:
          type: string
          nullable: true
        picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        followers:
          type: integer
          nullable: true
      required:
        - platform
    ConnectedSocialsQuery:
      type: object
      properties:
        platform:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - onlyfans
            - twitter
            - twitch
        handle:
          type: string
          description: >-
            Creator identifier — username, profile URL, or YouTube channel ID
            (UC...).
      required:
        - platform
        - handle
      example:
        platform: instagram
        handle: creator_handle
    ConnectedSocialsResponse:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/ConnectedSocial'
        credits_cost:
          type: number
          format: double
          example: 0.5
        response_meta:
          type: object
          additionalProperties: {}
      required:
        - result
        - credits_cost
        - response_meta
    CreateCampaignInput:
      type: object
      properties:
        name:
          type: string
          description: >-
            Campaign name. Must be unique among the client's non-archived
            campaigns.
        tracking_keywords:
          type: array
          items:
            type: string
          description: >-
            Keywords whose presence in a creator's posts marks the post as
            campaign content. Optional.
        brief:
          type: string
          description: Free-text campaign brief.
          default: ''
        platforms:
          type: array
          items:
            type: string
          description: >-
            Platforms the campaign tracks. One subscription is created per
            platform; duplicates are rejected.
        content_types:
          type: array
          items:
            type: string
          description: >-
            Post types counted as campaign content (e.g. 'post', 'reel',
            'video', 'story').
        start_date:
          type: string
          format: date
          description: Date the campaign begins tracking (ISO 8601). Cannot be in the past.
        end_date:
          type: string
          format: date
          description: >-
            Date the campaign stops tracking (ISO 8601). Must be after
            start_date.
        budget:
          type: string
          format: decimal
          description: Optional campaign budget.
          nullable: true
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
      required:
        - name
        - platforms
        - content_types
        - start_date
        - end_date
    CreateCampaignInputRequest:
      type: object
      properties:
        name:
          type: string
          description: >-
            Campaign name. Must be unique among the client's non-archived
            campaigns.
        tracking_keywords:
          type: array
          items:
            type: string
          description: >-
            Keywords whose presence in a creator's posts marks the post as
            campaign content. Optional.
        brief:
          type: string
          description: Free-text campaign brief.
          default: ''
        platforms:
          type: array
          items:
            type: string
          description: >-
            Platforms the campaign tracks. One subscription is created per
            platform; duplicates are rejected.
        content_types:
          type: array
          items:
            type: string
          description: >-
            Post types counted as campaign content (e.g. 'post', 'reel',
            'video', 'story').
        start_date:
          type: string
          format: date
          description: Date the campaign begins tracking (ISO 8601). Cannot be in the past.
        end_date:
          type: string
          format: date
          description: >-
            Date the campaign stops tracking (ISO 8601). Must be after
            start_date.
        budget:
          type: string
          format: decimal
          description: Optional campaign budget.
          nullable: true
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
      required:
        - name
        - platforms
        - content_types
        - start_date
        - end_date
    CreateSubscriptionInput:
      type: object
      properties:
        name:
          type: string
          description: Optional subscription name.
        platform:
          type: string
          description: >-
            Platform to monitor. Optional when it can be derived from list_ids;
            required otherwise. Exactly one platform per subscription.
        event_type:
          type: string
          description: >-
            Event that triggers a notification (e.g. 'new_post', 'bio_change',
            'follower_threshold').
        filters:
          type: object
          description: >-
            Event-type-specific filter object. Required for
            'follower_threshold'; shape is validated against the chosen
            event_type.
          additionalProperties: {}
        list_ids:
          type: array
          items:
            type: integer
          description: >-
            Discovery list IDs whose creators are monitored. Provide handles
            and/or list_ids.
        notify_endpoints:
          type: array
          items:
            $ref: '#/components/schemas/NotifyEndpointInput'
          description: Where matching events are delivered. At least one is required.
        handles:
          type: array
          items:
            type: string
          description: Creator handles to monitor. Provide handles and/or list_ids.
      required:
        - event_type
        - notify_endpoints
    CreateSubscriptionInputRequest:
      type: object
      properties:
        name:
          type: string
          description: Optional subscription name.
        platform:
          type: string
          description: >-
            Platform to monitor. Optional when it can be derived from list_ids;
            required otherwise. Exactly one platform per subscription.
        event_type:
          type: string
          description: >-
            Event that triggers a notification (e.g. 'new_post', 'bio_change',
            'follower_threshold').
        filters:
          type: object
          description: >-
            Event-type-specific filter object. Required for
            'follower_threshold'; shape is validated against the chosen
            event_type.
          additionalProperties: {}
        list_ids:
          type: array
          items:
            type: integer
          description: >-
            Discovery list IDs whose creators are monitored. Provide handles
            and/or list_ids.
        notify_endpoints:
          type: array
          items:
            $ref: '#/components/schemas/NotifyEndpointInput'
          description: Where matching events are delivered. At least one is required.
        handles:
          type: array
          items:
            type: string
          description: Creator handles to monitor. Provide handles and/or list_ids.
      required:
        - event_type
        - notify_endpoints
    CreatorContentDetails:
      type: object
      properties:
        platform:
          type: string
          description: 'Social media platform. Allowed: instagram, tiktok, youtube.'
        content_type:
          type: string
          description: Type of content to fetch. Platform-specific.
        post_id:
          type: string
          description: ID of the post, e.g., '3702042988674165349_1541770582'.
        pagination_token:
          type: string
          description: Pagination token, optional.
      required:
        - platform
        - content_type
        - post_id
      example:
        platform: instagram
        content_type: data
        post_id: 3702042988674165349_1541770582
        pagination_token: ''
    CreatorContentDetailsRequest:
      type: object
      properties:
        platform:
          type: string
          description: 'Social media platform. Allowed: instagram, tiktok, youtube.'
        content_type:
          type: string
          description: Type of content to fetch. Platform-specific.
        post_id:
          type: string
          description: ID of the post, e.g., '3702042988674165349_1541770582'.
        pagination_token:
          type: string
          description: Pagination token, optional.
      required:
        - platform
        - content_type
        - post_id
      example:
        platform: instagram
        content_type: data
        post_id: 3702042988674165349_1541770582
        pagination_token: ''
    CreatorContentDetailsResponse:
      type: object
      properties:
        credits_cost:
          type: number
          format: double
          nullable: true
          example: 0.03
        result:
          type: object
          description: A dictionary of arbitrary key-value pairs.
          additionalProperties: {}
      x-expandLevel: 2
    CreatorHas:
      type: object
      properties:
        has_amazonaffiliates:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_applemusic:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_bandcamp:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_behance:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_buymeacoffee:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_cameo:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_canva:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_clubhouse:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_discord:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_dribbble:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_etsy:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_facebook:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_fiverr:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_github:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_gofundme:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_goodreads:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_instagram:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_kakao:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_kickstarter:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_kofi:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_linkedin:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_linktree:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_medium:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_onlyfans:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_patreon:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_personal_website:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators with a website on
            their Instagram, TikTok or YouTube profile. Sending false or null
            has no effect (equivalent to omitting the field).
          nullable: true
          default: false
        has_phone:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_pinterest:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_podcast:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_redbubble:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_shopify:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_shopltk:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_snapchat:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_spotify:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_spring:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_streamlabs:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_substack:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_telegram:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_tiktok:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_tumblr:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_twitch:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_twitter:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_udemy:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_viber:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_vimeo:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_vk:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_weebly:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_whatsApp:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_youtube:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_wix:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_anchor:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_soundcloud:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_community:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
    CreatorHasRequest:
      type: object
      properties:
        has_amazonaffiliates:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_applemusic:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_bandcamp:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_behance:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_buymeacoffee:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_cameo:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_canva:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_clubhouse:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_discord:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_dribbble:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_etsy:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_facebook:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_fiverr:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_github:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_gofundme:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_goodreads:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_instagram:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_kakao:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_kickstarter:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_kofi:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_linkedin:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_linktree:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_medium:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_onlyfans:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_patreon:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_personal_website:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators with a website on
            their Instagram, TikTok or YouTube profile. Sending false or null
            has no effect (equivalent to omitting the field).
          nullable: true
          default: false
        has_phone:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_pinterest:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_podcast:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_redbubble:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_shopify:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_shopltk:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_snapchat:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_spotify:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_spring:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_streamlabs:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_substack:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_telegram:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_tiktok:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_tumblr:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_twitch:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_twitter:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_udemy:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_viber:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_vimeo:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_vk:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_weebly:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_whatsApp:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_youtube:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_wix:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_anchor:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_soundcloud:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
        has_community:
          type: boolean
          description: >-
            Only true is meaningful. Filters for creators who have this
            platform/link. Sending false or null has no effect (equivalent to
            omitting the field).
          nullable: true
          default: false
    CreatorPostsQuery:
      type: object
      properties:
        count:
          type: integer
          description: >-
            Number of posts to fetch per page. Clamped to platform-specific
            limits.
        pagination_token:
          type: string
          description: Cursor for fetching the next page of results.
        platform:
          type: string
          description: 'Social media platform. Allowed: instagram, tiktok, youtube.'
        handle:
          type: string
          description: >-
            Creator identifier — username, profile URL, or YouTube channel ID
            (UC...).
      required:
        - platform
        - handle
      example:
        platform: instagram
        handle: creator_handle
        count: 12
        pagination_token: ''
    CreatorPostsResponse:
      type: object
      properties:
        credits_cost:
          type: number
          format: double
          nullable: true
          example: 0.03
        result:
          $ref: '#/components/schemas/CreatorPostsResult'
      required:
        - result
    CreatorPostsResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/PostItemModel'
        num_results:
          type: integer
        more_available:
          type: boolean
        next_token:
          type: string
          nullable: true
        status:
          type: string
          default: ok
      required:
        - items
        - num_results
        - more_available
    DiscoveryAPIResponse:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        credits_left:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/AccountResponse'
      required:
        - total
        - limit
        - credits_left
    DiscoveryAPISearchInputRequest:
      oneOf:
        - $ref: '#/components/schemas/DiscoveryInstagramRequest'
        - $ref: '#/components/schemas/DiscoveryYouTubeRequest'
        - $ref: '#/components/schemas/DiscoveryTikTokRequest'
        - $ref: '#/components/schemas/DiscoveryTwitterRequest'
        - $ref: '#/components/schemas/DiscoveryTwitchRequest'
        - $ref: '#/components/schemas/DiscoveryOnlyFansRequest'
      discriminator:
        propertyName: platform
        mapping:
          instagram: '#/components/schemas/DiscoveryInstagramRequest'
          youtube: '#/components/schemas/DiscoveryYouTubeRequest'
          tiktok: '#/components/schemas/DiscoveryTikTokRequest'
          twitter: '#/components/schemas/DiscoveryTwitterRequest'
          twitch: '#/components/schemas/DiscoveryTwitchRequest'
          onlyfans: '#/components/schemas/DiscoveryOnlyFansRequest'
    DiscoveryFiltersRequest:
      type: object
      description: >-
        Discovery filters are platform-dependent.


        The API accepts a superset of all filters across platforms, but only a
        subset is applied

        depending on the selected `platform` in the request.


        We annotate fields with "Supported platforms" in the OpenAPI schema so
        users can

        understand what applies where (Redocly cannot dynamically change the
        form based on

        the selected platform).
      properties:
        location:
          type: array
          items:
            type: string
            nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        type:
          type: string
          nullable: true
          description: 'Supported platforms: Instagram, YouTube, TikTok, Twitter'
        gender:
          type: string
          nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        profile_language:
          type: array
          items:
            type: string
            nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        ai_search:
          type: string
          nullable: true
          description: >-
            Finds creators matching a single niche (e.g., 'plant-based
            recipes'), 3-150 characters; only letters, numbers and # - / , . ! ?
            are supported. For best results, use one niche at a time—long or
            multi-topic phrases return weaker matches.
        creator_has:
          allOf:
            - $ref: '#/components/schemas/CreatorHasRequest'
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        exclude_role_based_emails:
          type: boolean
          nullable: true
          default: false
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        exclude_handles:
          type: array
          items:
            type: string
          nullable: true
          maxItems: 10000
          description: >-
            List of handles to exclude from search results. Supports up to
            10,000 entries. Values are normalized automatically (lowercased, @
            stripped, URLs parsed to extract handle). Replaces the deprecated
            exclude_all parameter.
        exclude_list:
          type: array
          items:
            type: integer
          description: >-
            IDs of exclusion lists to apply. Create and manage these via the
            [Exclusion lists](#tag/Exclusion-lists) endpoints, then pass their
            IDs here. Only lists for this platform are applied. Supported
            platforms: Instagram, YouTube, TikTok, Twitch, Twitter, OnlyFans
        exclude_default_list:
          type: boolean
          default: false
          description: >-
            When true, applies the team's [default exclusion
            list](#tag/Exclusion-lists) for this platform. Supported platforms:
            Instagram, YouTube, TikTok, Twitch, Twitter, OnlyFans
        exclude_all_lists:
          type: boolean
          default: false
          description: >-
            When true, applies every [exclusion list](#tag/Exclusion-lists) for
            this platform — both the default list and all specific lists.
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        number_of_followers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter'
        posting_frequency:
          type: number
          format: double
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, YouTube'
        follower_growth:
          allOf:
            - $ref: '#/components/schemas/GrowthRequest'
          nullable: true
          description: 'Supported platforms: Instagram, TikTok'
        average_likes:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter'
        average_comments:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Instagram, TikTok'
        average_views:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: TikTok'
        average_video_downloads:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: TikTok'
        has_tik_tok_shop:
          type: boolean
          nullable: true
          description: 'Supported platforms: TikTok'
        exclude_private_profile:
          type: boolean
          nullable: true
          description: 'Supported platforms: Instagram, TikTok'
        is_verified:
          type: boolean
          nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        has_link_in_bio:
          type: boolean
          nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        has_done_brand_deals:
          type: boolean
          nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        promotes_affiliate_links:
          type: boolean
          nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        does_live_streaming:
          type: boolean
          nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        keywords_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter'
        keywords_in_tweets:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Twitter'
        keywords_not_in_tweets:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Twitter'
        number_of_tweets:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        last_post:
          oneOf:
            - type: string
            - type: integer
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter'
        last_upload_long_video:
          oneOf:
            - type: string
            - type: integer
          nullable: true
          description: 'Supported platforms: YouTube'
        last_upload_short_video:
          oneOf:
            - type: string
            - type: integer
          nullable: true
          description: 'Supported platforms: YouTube'
        most_recent_stream_date:
          oneOf:
            - type: string
            - type: integer
          nullable: true
          description: 'Supported platforms: Twitch'
        last_active:
          oneOf:
            - type: string
            - type: integer
          nullable: true
          description: 'Supported platforms: OnlyFans'
        income:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Instagram, YouTube'
        number_of_subscribers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: YouTube'
        topics:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube'
        keywords_in_video_titles:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube'
        keywords_not_in_video_titles:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube'
        keywords_in_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube, Twitch'
        keywords_not_in_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube'
        keywords_in_video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube'
        keywords_not_in_video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube'
        exclude_keywords_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter'
        keywords_in_captions:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Instagram'
        keywords_not_in_captions:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Instagram'
        link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter, Twitch'
        not_link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter, Twitch'
        links_from_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube'
        links_from_video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: YouTube'
        hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter, YouTube'
        not_hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter, YouTube'
        not_video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: TikTok'
        video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: TikTok'
        tweets:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        subscriber_growth:
          allOf:
            - $ref: '#/components/schemas/GrowthRequest'
          nullable: true
          default:
            growth_percentage: null
            time_range_months: 3
          description: 'Supported platforms: YouTube'
        has_shorts:
          type: boolean
          nullable: true
          description: 'Supported platforms: YouTube'
        has_podcast:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: YouTube'
        has_videos:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: Instagram, OnlyFans'
        has_free_account:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: OnlyFans'
        has_live_streams:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: OnlyFans'
        has_courses:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: YouTube'
        has_membership:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: YouTube'
        has_live_videos:
          type: boolean
          nullable: true
          default: false
        shorts_percentage:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: YouTube'
        has_community_posts:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: YouTube'
        streams_live:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: YouTube'
        has_merch:
          type: boolean
          nullable: true
          default: false
          description: >-
            Supported platforms: Instagram, YouTube, TikTok, Twitch, Twitter,
            OnlyFans
        average_views_on_long_videos:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          description: 'Supported platforms: YouTube'
        median_views_long:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_views_on_shorts:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: YouTube'
        number_of_videos:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: YouTube'
        video_count:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: TikTok'
        tweets_count:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Twitter'
        is_monetizing:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: YouTube'
        long_video_duration:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: YouTube'
        average_stream_views:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: YouTube'
        average_stream_duration:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: YouTube'
        last_stream_upload:
          oneOf:
            - type: string
            - type: integer
          nullable: true
          description: 'Supported platforms: YouTube'
        number_of_posts:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Instagram'
        reels_percent:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Instagram'
        average_views_for_reels:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Instagram'
        subscription_price:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: OnlyFans'
        number_of_photos:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: OnlyFans'
        number_of_likes:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: OnlyFans'
        followers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Twitch'
        active_subscribers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Twitch'
        streamed_hours_last_30_days:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Twitch'
        total_hours_streamed:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Twitch'
        maximum_views_count:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Twitch'
        avg_views_last_30_days:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          description: 'Supported platforms: Twitch'
        streams_count_last_30_days:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Twitch'
        games_played:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
          description: 'Supported platforms: Twitch'
        is_twitch_partner:
          type: boolean
          nullable: true
          default: false
          description: 'Supported platforms: Twitch'
        engagement_percent:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
          description: 'Supported platforms: Instagram, TikTok, Twitter, YouTube'
    DiscoveryInstagramRequest:
      type: object
      required:
        - platform
        - paging
        - filters
      properties:
        platform:
          type: string
          enum:
            - instagram
        nlp_search:
          type: string
          nullable: true
          description: >-
            Natural-language brief describing who you're looking for (e.g.
            "fitness creators in New York with over 100k followers"). It's
            mapped to discovery filters by AI to fill in fields you didn't set —
            your explicit `filters` take precedence. The search always runs on
            the `platform` you send; if the brief names another platform it's
            ignored.
        paging:
          $ref: '#/components/schemas/PagingRequest'
        sort:
          $ref: '#/components/schemas/SortRequest'
        filters:
          $ref: '#/components/schemas/InstagramDiscoveryFilters'
    DiscoveryOnlyFansRequest:
      type: object
      required:
        - platform
        - paging
        - filters
      properties:
        platform:
          type: string
          enum:
            - onlyfans
        nlp_search:
          type: string
          nullable: true
          description: >-
            Natural-language brief describing who you're looking for (e.g.
            "fitness creators in New York with over 100k followers"). It's
            mapped to discovery filters by AI to fill in fields you didn't set —
            your explicit `filters` take precedence. The search always runs on
            the `platform` you send; if the brief names another platform it's
            ignored.
        paging:
          $ref: '#/components/schemas/PagingRequest'
        sort:
          $ref: '#/components/schemas/SortRequest'
        filters:
          $ref: '#/components/schemas/OnlyFansDiscoveryFilters'
    DiscoverySearchResponse:
      type: object
      properties:
        total:
          type: integer
        limit:
          type: integer
        credits_left:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/AccountResponse'
        applied_filters:
          type: object
          description: >-
            The effective filter set the search ran with — your explicit
            `filters` layered over anything the AI inferred.
          additionalProperties: {}
        nlp_search:
          $ref: '#/components/schemas/NlpSearchEcho'
          description: >-
            What the AI inferred from the brief, what you overrode, and why
            anything was dropped.
      required:
        - total
        - limit
        - credits_left
    DiscoveryTikTokRequest:
      type: object
      required:
        - platform
        - paging
        - filters
      properties:
        platform:
          type: string
          enum:
            - tiktok
        nlp_search:
          type: string
          nullable: true
          description: >-
            Natural-language brief describing who you're looking for (e.g.
            "fitness creators in New York with over 100k followers"). It's
            mapped to discovery filters by AI to fill in fields you didn't set —
            your explicit `filters` take precedence. The search always runs on
            the `platform` you send; if the brief names another platform it's
            ignored.
        paging:
          $ref: '#/components/schemas/PagingRequest'
        sort:
          $ref: '#/components/schemas/SortRequest'
        filters:
          $ref: '#/components/schemas/TikTokDiscoveryFilters'
    DiscoveryTwitchRequest:
      type: object
      required:
        - platform
        - paging
        - filters
      properties:
        platform:
          type: string
          enum:
            - twitch
        nlp_search:
          type: string
          nullable: true
          description: >-
            Natural-language brief describing who you're looking for (e.g.
            "fitness creators in New York with over 100k followers"). It's
            mapped to discovery filters by AI to fill in fields you didn't set —
            your explicit `filters` take precedence. The search always runs on
            the `platform` you send; if the brief names another platform it's
            ignored.
        paging:
          $ref: '#/components/schemas/PagingRequest'
        sort:
          $ref: '#/components/schemas/SortRequest'
        filters:
          $ref: '#/components/schemas/TwitchDiscoveryFilters'
    DiscoveryTwitterRequest:
      type: object
      required:
        - platform
        - paging
        - filters
      properties:
        platform:
          type: string
          enum:
            - twitter
        nlp_search:
          type: string
          nullable: true
          description: >-
            Natural-language brief describing who you're looking for (e.g.
            "fitness creators in New York with over 100k followers"). It's
            mapped to discovery filters by AI to fill in fields you didn't set —
            your explicit `filters` take precedence. The search always runs on
            the `platform` you send; if the brief names another platform it's
            ignored.
        paging:
          $ref: '#/components/schemas/PagingRequest'
        sort:
          $ref: '#/components/schemas/SortRequest'
        filters:
          $ref: '#/components/schemas/TwitterDiscoveryFilters'
    DiscoveryYouTubeRequest:
      type: object
      required:
        - platform
        - paging
        - filters
      properties:
        platform:
          type: string
          enum:
            - youtube
        nlp_search:
          type: string
          nullable: true
          description: >-
            Natural-language brief describing who you're looking for (e.g.
            "fitness creators in New York with over 100k followers"). It's
            mapped to discovery filters by AI to fill in fields you didn't set —
            your explicit `filters` take precedence. The search always runs on
            the `platform` you send; if the brief names another platform it's
            ignored.
        paging:
          $ref: '#/components/schemas/PagingRequest'
        sort:
          $ref: '#/components/schemas/SortRequest'
        filters:
          $ref: '#/components/schemas/YouTubeDiscoveryFilters'
    EngagementModel:
      type: object
      properties:
        likes:
          type: integer
          nullable: true
        comments:
          type: integer
          nullable: true
        views:
          type: integer
          nullable: true
    EnrichAnalyticsHandleRequest:
      type: object
      properties:
        handle:
          type: string
          description: >-
            Creator identifier — username, profile URL, or YouTube channel ID
            (UC...).
        platform:
          type: string
          enum:
            - instagram
            - onlyfans
            - tiktok
            - twitch
            - twitter
            - youtube
          description: >-
            Platform to enrich from — only platforms with analytics data are
            accepted.
        include_lookalikes:
          type: boolean
          description: >-
            Whether to include lookalike creator recommendations in the
            response.
          nullable: true
          default: false
      required:
        - handle
        - platform
    EnrichBasicEmailRequest:
      type: object
      properties:
        email:
          type: string
          description: The creator's email address.
      required:
        - email
      example:
        email: creator@example.com
    EnrichFullHandleRequest:
      type: object
      properties:
        handle:
          type: string
          description: >-
            Creator identifier — username, profile URL, or YouTube channel ID
            (UC...).
        platform:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - onlyfans
            - twitter
            - snapchat
            - discord
            - pinterest
            - facebook
            - linkedin
            - twitch
          description: Platform to enrich from (e.g., instagram, youtube).
        email_required:
          type: string
          enum:
            - must_have
            - preferred
          nullable: true
          description: >-
            Whether a validated email is required: 'must_have' rejects the match
            if no valid email is found (no credits charged), 'preferred' returns
            the match regardless. Defaults to 'preferred'.
          default: preferred
        include_lookalikes:
          type: boolean
          description: >-
            Whether to include lookalike creator recommendations in the
            response.
          nullable: true
          default: false
        include_audience_data:
          type: boolean
          description: Whether to include audience demographic data in the response.
          nullable: true
          default: true
      required:
        - handle
        - platform
      example:
        handle: creator_handle
        platform: instagram
        email_required: preferred
        include_lookalikes: false
        include_audience_data: true
    EnrichProfileHandleRequest:
      type: object
      properties:
        handle:
          type: string
          description: >-
            Creator identifier — username, profile URL, or YouTube channel ID
            (UC...).
        platform:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - onlyfans
            - twitter
            - snapchat
            - discord
            - pinterest
            - facebook
            - linkedin
            - twitch
          description: Platform to enrich from (e.g., instagram, youtube).
        email_required:
          type: string
          enum:
            - must_have
            - preferred
          nullable: true
          description: >-
            Whether a validated email is required: 'must_have' rejects the match
            if no valid email is found (no credits charged), 'preferred' returns
            the match regardless. Defaults to 'preferred'.
          default: preferred
      required:
        - handle
        - platform
    EnrichRawHandleRequest:
      type: object
      properties:
        handle:
          type: string
          description: >-
            Creator identifier — username, profile URL, or YouTube channel ID
            (UC...).
        platform:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - onlyfans
            - twitter
            - snapchat
            - discord
            - pinterest
            - facebook
            - linkedin
            - twitch
          description: Platform to enrich from (e.g., instagram, youtube).
      required:
        - handle
        - platform
      example:
        handle: creator_handle
        platform: instagram
    EnrichSimilarCreatorsRequest:
      oneOf:
        - $ref: '#/components/schemas/SimilarCreatorsInstagramRequest'
        - $ref: '#/components/schemas/SimilarCreatorsYouTubeRequest'
        - $ref: '#/components/schemas/SimilarCreatorsTikTokRequest'
        - $ref: '#/components/schemas/SimilarCreatorsTwitterRequest'
        - $ref: '#/components/schemas/SimilarCreatorsTwitchRequest'
        - $ref: '#/components/schemas/SimilarCreatorsOnlyFansRequest'
      discriminator:
        propertyName: platform
        mapping:
          instagram: '#/components/schemas/SimilarCreatorsInstagramRequest'
          youtube: '#/components/schemas/SimilarCreatorsYouTubeRequest'
          tiktok: '#/components/schemas/SimilarCreatorsTikTokRequest'
          twitter: '#/components/schemas/SimilarCreatorsTwitterRequest'
          twitch: '#/components/schemas/SimilarCreatorsTwitchRequest'
          onlyfans: '#/components/schemas/SimilarCreatorsOnlyFansRequest'
      example:
        platform: instagram
        filter_key: username
        filter_value: creator_handle
        paging:
          page: 0
          limit: 10
    ErrorResponse:
      type: object
      title: ErrorResponse
      required:
        - error_code
      properties:
        error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
            - type: array
              items: {}
          description: >-
            Human-readable description of what went wrong. Shape varies per
            endpoint: string on most paths, DRF field-error object on validation
            paths of creators_api enrich/* and enrichment_batch_api create, list
            of strings on discovery filter validation. See the per-endpoint
            example response.
          example: Insufficient credits.
        error_code:
          type: string
          description: >-
            Machine-readable snake_case slug identifying the error class. Stable
            across API versions; **the only field guaranteed present on every
            public-API error**. Use for programmatic branching instead of
            parsing `error`.
          example: insufficient_credits
        message:
          type: string
          description: >-
            Optional long-form detail sibling to `error`. Present on endpoints
            that historically returned both a short label and a long explanation
            (rate limits, polling, batch state, insufficient_credits on resume).
          example: >-
            Poll every 30-60 seconds. Excessive polling results in rate
            limiting.
        retry_after:
          type: integer
          description: >-
            Seconds the caller should wait before retrying. Present on 429s
            where the OLD endpoint set it; mirrored in the `Retry-After` HTTP
            header.
          example: 60
        response_meta:
          type: object
          description: >-
            Echo of request metadata on a few unwrapped endpoints (notably
            download_batch_enrichment_csv: batch_id, batch_status).
            Internal-only on wrapped endpoints; stripped before reaching the
            client.
          additionalProperties: true
        available_credits:
          type: number
          format: float
          description: >-
            Credits currently available. Present on the 403 insufficient_credits
            response of `POST /public/v1/enrichment/batch/{id}/resume/`.
        required_minimum:
          type: number
          format: float
          description: Minimum credits needed. Pairs with `available_credits`.
        current_status:
          type: string
          description: >-
            Current resource state. Present on 400 responses where the operation
            requires a different state (e.g. `batch_not_ready`,
            `batch_not_resumable`).
        active_batches:
          type: integer
          description: 'Active batch count when `error_code: batch_limit_reached`.'
        max_allowed:
          type: integer
          description: Per-client batch ceiling. Pairs with `active_batches`.
      description: >-
        Loose union of every public-API error body. Only `error_code` is
        guaranteed present; everything else varies per endpoint. See
        public_api/ERROR_HANDLING.md for the error_code taxonomy and
        per-endpoint shape notes.
    EventCreator:
      type: object
      properties:
        platform:
          type: string
          description: The creator's social media platform.
        platform_id:
          type: string
          description: The creator's handle on the platform.
      required:
        - platform
        - platform_id
    EventDelivery:
      type: object
      properties:
        id:
          type: integer
        endpoint:
          $ref: '#/components/schemas/NotifyEndpoint'
          description: The notify endpoint this delivery was sent to.
        status:
          type: string
        retries:
          type: integer
        status_code:
          type: integer
          nullable: true
        response_time:
          type: number
          format: double
          nullable: true
        sent_date:
          type: string
          format: date-time
          nullable: true
        redeliver_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - endpoint
        - status
        - retries
        - created_at
        - updated_at
    EventDetail:
      type: object
      properties:
        payload:
          type: string
          description: The webhook payload exactly as it was sent to the endpoint.
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/EventDelivery'
          description: Full delivery history for the event.
      required:
        - deliveries
    EventListPage:
      type: object
      properties:
        count:
          type: integer
          description: Total number of events matching the filter.
        next:
          type: string
          format: uri
          description: URL of the next page, or null on the last page.
          nullable: true
        previous:
          type: string
          format: uri
          description: URL of the previous page, or null on the first page.
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/EventResponse'
          description: Events on the current page.
      required:
        - count
        - results
    EventResponse:
      type: object
      properties:
        id:
          type: integer
        event_type:
          type: string
        event_value:
          type: object
          nullable: true
          additionalProperties: {}
        creator:
          $ref: '#/components/schemas/EventCreator'
          description: The creator the event fired for.
        date_occurance:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        delivery_status:
          type: string
          description: Delivery status of the event (pending/sending/sent/failed/retrying).
        latency_seconds:
          type: string
          description: Response time of the first successful delivery, in seconds.
        retries:
          type: string
          description: Total retry count across all delivery attempts.
      required:
        - id
        - event_type
        - creator
        - date_occurance
        - created_at
    ExclusionEntriesInputRequest:
      type: object
      properties:
        handles:
          type: array
          items:
            type: string
          description: >-
            Handles to add to or remove from the list. Normalized automatically
            (lowercased, @ stripped, URLs parsed to extract the handle).
      required:
        - handles
    ExclusionEntriesResponse:
      type: object
      properties:
        total:
          type: integer
          description: Total number of handles in the list.
        offset:
          type: integer
          description: Offset applied to this page of handles.
        limit:
          type: integer
          description: Limit applied to this page of handles.
        handles:
          type: array
          items:
            type: string
          description: The requested page of handles, sorted alphabetically.
      required:
        - total
        - offset
        - limit
        - handles
      example:
        total: 3
        offset: 0
        limit: 1000
        handles:
          - creator_one
          - creator_three
          - creator_two
    ExclusionList:
      type: object
      properties:
        id:
          type: integer
          description: The exclusion list's unique identifier.
        name:
          type: string
          description: Human-readable name of the exclusion list.
        platform:
          type: string
          description: The social media platform this list applies to.
        is_default:
          type: boolean
          description: Whether this is the team's default list for the platform.
        handle_count:
          type: integer
          description: Number of handles currently in the list.
        created_at:
          type: string
          format: date-time
          description: When the list was created.
        updated_at:
          type: string
          format: date-time
          description: When the list was last modified.
      required:
        - id
        - name
        - platform
        - is_default
        - handle_count
        - created_at
        - updated_at
      example:
        id: 42
        name: Blocklist Q4
        platform: instagram
        is_default: false
        handle_count: 3
        created_at: '2026-01-15T09:30:00Z'
        updated_at: '2026-01-20T14:05:00Z'
    ExclusionListCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: Human-readable name for the new exclusion list.
        platform:
          type: string
          enum:
            - instagram
            - youtube
            - tiktok
            - twitch
            - twitter
            - onlyfans
          description: The social media platform this list applies to.
      required:
        - name
        - platform
    ExclusionListUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: New name for the exclusion list.
      required:
        - name
    Growth:
      type: object
      properties:
        growth_percentage:
          type: number
          format: double
          nullable: true
        time_range_months:
          type: integer
          nullable: true
          default: 3
    GrowthRequest:
      type: object
      properties:
        growth_percentage:
          type: number
          format: double
          nullable: true
        time_range_months:
          type: integer
          nullable: true
          default: 3
    HandleAnalyticsInstagramResponse:
      type: object
      properties:
        audience:
          allOf:
            - $ref: '#/components/schemas/AudienceDataResponse'
          nullable: true
        brand_affinity:
          type: array
          items:
            $ref: '#/components/schemas/BrandAffinityResponse'
        brands_found:
          type: array
          items:
            type: object
            additionalProperties: {}
        comments_median:
          type: number
          format: double
          nullable: true
        creator_follower_growth:
          type: object
          nullable: true
          additionalProperties: {}
        has_merch:
          type: boolean
        hashtags:
          type: array
          items:
            type: string
        hashtags_count:
          type: array
          items:
            type: object
            additionalProperties: {}
        income:
          type: object
          nullable: true
          additionalProperties: {}
        likes_median:
          type: number
          format: double
          nullable: true
        locations:
          type: array
          items:
            type: string
        niche_sub_class:
          type: array
          items:
            type: string
        past_sponsors:
          type: array
          items:
            $ref: '#/components/schemas/PastSponsorResponse'
        posting_frequency_recent_months:
          type: number
          format: double
          nullable: true
        promotes_affiliate_links:
          type: boolean
        reels:
          type: object
          nullable: true
          additionalProperties: {}
        reels_percentage_last_12_posts:
          type: number
          format: double
          nullable: true
        sponsored_posts:
          type: array
          items:
            $ref: '#/components/schemas/SponsoredPostResponse'
        tagged:
          type: array
          items:
            type: object
            additionalProperties: {}
    HandleAnalyticsOnlyfansResponse:
      type: object
      properties:
        archived_posts_count:
          type: integer
          nullable: true
        audios_count:
          type: integer
          nullable: true
        avg_durations:
          type: number
          format: double
          nullable: true
        comments_median:
          type: number
          format: double
          nullable: true
        finished_streams_count:
          type: integer
          nullable: true
        has_merch:
          type: boolean
        has_paid_partnership:
          type: boolean
        is_spotify_connected:
          type: boolean
        likes_median:
          type: number
          format: double
          nullable: true
        photos_count:
          type: integer
          nullable: true
        post_dates:
          type: array
          items:
            type: string
        post_durations:
          type: array
          items:
            type: number
            format: double
        posts_count:
          type: integer
          nullable: true
        private_archived_posts_count:
          type: integer
          nullable: true
        promotes_affiliate_links:
          type: boolean
        referal_bonus_sum_for_referer:
          type: integer
          nullable: true
        tips_enabled:
          type: boolean
        tips_max:
          type: integer
          nullable: true
        tips_min:
          type: integer
          nullable: true
        tips_min_internal:
          type: integer
          nullable: true
        tips_text_enabled:
          type: boolean
        total_likes:
          type: integer
          nullable: true
        videos_count:
          type: integer
          nullable: true
    HandleAnalyticsPlatformResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/HandleAnalyticsResultResponse'
        credits_cost:
          type: number
          format: double
          nullable: true
          example: 0.8
    HandleAnalyticsResultResponse:
      type: object
      properties:
        audience_interests:
          type: array
          items:
            type: object
            additionalProperties: {}
        lookalikes:
          type: array
          items:
            type: object
            additionalProperties: {}
        instagram:
          $ref: '#/components/schemas/HandleAnalyticsInstagramResponse'
        youtube:
          $ref: '#/components/schemas/HandleAnalyticsYoutubeResponse'
        tiktok:
          $ref: '#/components/schemas/HandleAnalyticsTiktokResponse'
        onlyfans:
          $ref: '#/components/schemas/HandleAnalyticsOnlyfansResponse'
        twitter:
          $ref: '#/components/schemas/HandleAnalyticsTwitterResponse'
        twitch:
          $ref: '#/components/schemas/HandleAnalyticsTwitchResponse'
    HandleAnalyticsTiktokResponse:
      type: object
      properties:
        audience:
          allOf:
            - $ref: '#/components/schemas/AudienceDataResponse'
          nullable: true
        brands_found:
          type: array
          items:
            type: string
        challenges_list:
          type: array
          items:
            type: string
        comment_count_avg:
          type: number
          format: double
          nullable: true
        comments_median:
          type: number
          format: double
          nullable: true
        creator_follower_growth:
          type: object
          nullable: true
          additionalProperties: {}
        duration_avg:
          type: number
          format: double
          nullable: true
        has_merch:
          type: boolean
        hashtags:
          type: array
          items:
            type: string
        likes_median:
          type: number
          format: double
          nullable: true
        niche_sub_class:
          type: array
          items:
            type: string
        play_count_avg:
          type: number
          format: double
          nullable: true
        play_count_median:
          type: number
          format: double
          nullable: true
        posting_frequency:
          type: integer
          nullable: true
        posting_frequency_recent_months:
          type: number
          format: double
          nullable: true
        promotes_affiliate_links:
          type: boolean
        reach_score:
          type: number
          format: double
          nullable: true
        reach_score_list:
          type: array
          items:
            type: number
            format: double
        saves_count_list:
          type: array
          items:
            type: integer
        saves_median:
          type: number
          format: double
          nullable: true
        shares_median:
          type: number
          format: double
          nullable: true
        tagged:
          type: array
          items:
            type: string
        total_likes:
          type: integer
          nullable: true
        total_saves:
          type: integer
          nullable: true
        total_shares:
          type: integer
          nullable: true
    HandleAnalyticsTwitchResponse:
      type: object
      properties:
        avg_views:
          type: number
          format: double
          nullable: true
        has_merch:
          type: boolean
        has_paid_partnership:
          type: boolean
        last_broadcast_game:
          type: string
          nullable: true
        last_broadcast_id:
          type: string
          nullable: true
        last_streamed:
          type: string
          nullable: true
        primary_team_display_name:
          type: string
          nullable: true
        primary_team_name:
          type: string
          nullable: true
        promotes_affiliate_links:
          type: boolean
        streamed_hours_last_30_days:
          type: number
          format: double
          nullable: true
        streams_count_last_30_days:
          type: integer
          nullable: true
    HandleAnalyticsTwitterResponse:
      type: object
      properties:
        avg_quotes:
          type: number
          format: double
          nullable: true
        avg_reply:
          type: number
          format: double
          nullable: true
        avg_retweet:
          type: number
          format: double
          nullable: true
        avg_views:
          type: number
          format: double
          nullable: true
        creator_favorite_count:
          type: integer
          nullable: true
        has_merch:
          type: boolean
        has_paid_partnership:
          type: boolean
        hashtags:
          type: array
          items:
            type: string
        languages_tweet:
          type: array
          items:
            type: string
        platforms:
          type: object
          nullable: true
          additionalProperties: {}
        promotes_affiliate_links:
          type: boolean
        recommended_users:
          type: array
          items:
            type: string
        retweet_users:
          type: array
          items:
            type: string
        retweets_count:
          type: array
          items:
            type: string
        tagged:
          type: array
          items:
            type: string
        tagged_usernames:
          type: array
          items:
            type: string
        tweets_count:
          type: integer
          nullable: true
        tweets_frequency_recent_months:
          type: number
          format: double
          nullable: true
        tweets_type:
          type: object
          nullable: true
          additionalProperties: {}
    HandleAnalyticsYoutubeResponse:
      type: object
      properties:
        audience:
          allOf:
            - $ref: '#/components/schemas/AudienceDataResponse'
          nullable: true
        avg_views_long:
          type: number
          format: double
          nullable: true
        avg_views_shorts:
          type: number
          format: double
          nullable: true
        engagement_by_comments_and_views_long:
          type: number
          format: double
          nullable: true
        engagement_by_comments_and_views_shorts:
          type: number
          format: double
          nullable: true
        engagement_by_likes_and_views_long:
          type: number
          format: double
          nullable: true
        engagement_by_likes_and_views_shorts:
          type: number
          format: double
          nullable: true
        engagement_by_views_and_subs_long:
          type: number
          format: double
          nullable: true
        engagement_by_views_and_subs_shorts:
          type: number
          format: double
          nullable: true
        engagement_percent_long:
          type: number
          format: double
          nullable: true
        engagement_percent_shorts:
          type: number
          format: double
          nullable: true
        hashtags_count:
          type: array
          items:
            type: object
            additionalProperties: {}
        income:
          type: object
          nullable: true
          additionalProperties: {}
        keywords:
          type: array
          items:
            type: string
        last_long_video_upload_date:
          type: string
          nullable: true
        last_short_video_upload_date:
          type: string
          nullable: true
        least_views:
          type: integer
          nullable: true
        median_views_long:
          type: number
          format: double
          nullable: true
        niche_sub_class:
          type: array
          items:
            type: string
        posting_frequency:
          type: number
          format: double
          nullable: true
        posting_frequency_long:
          type: number
          format: double
          nullable: true
        posting_frequency_recent_months:
          type: number
          format: double
          nullable: true
        posting_frequency_shorts:
          type: number
          format: double
          nullable: true
        posts_per_month:
          type: object
          nullable: true
          additionalProperties: {}
        promotes_affiliate_links:
          type: boolean
        shorts_percentage:
          type: number
          format: double
          nullable: true
        topic_details:
          type: array
          items:
            type: string
        total_comments_last_50:
          type: integer
          nullable: true
        video_categories:
          type: array
          items:
            type: string
        video_hashtags:
          type: array
          items:
            type: string
        video_tags:
          type: array
          items:
            type: string
        video_topics:
          type: array
          items:
            type: string
    HandleEmailPlatformResponse:
      type: object
      properties:
        platform:
          type: string
          description: The creator's social media platform.
          nullable: true
        userId:
          type: string
          nullable: true
        url:
          type: string
          description: The creator's profile URL.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        fullname:
          type: string
          nullable: true
        picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        followers:
          type: integer
          nullable: true
    HandleEmailResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/HandleEmailPlatformResponse'
        credits_cost:
          type: number
          format: double
          nullable: true
          example: 0.05
    HandleFullFacebookResponse:
      type: object
      properties:
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        user_info:
          type: object
          nullable: true
          additionalProperties: {}
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        post_data:
          type: object
          nullable: true
          additionalProperties: {}
    HandleFullInstagramResponse:
      type: object
      properties:
        account_type:
          type: integer
          nullable: true
        avg_comments:
          type: number
          format: double
          nullable: true
        avg_likes:
          type: number
          format: double
          nullable: true
        biography:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        contact_phone_number:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        full_name:
          type: string
          nullable: true
        has_profile_pic:
          type: boolean
        is_business_account:
          type: boolean
        is_private:
          type: boolean
        is_verified:
          type: boolean
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        location_source:
          type: array
          items:
            type: string
        media_count:
          type: integer
          nullable: true
        most_recent_post_date:
          type: string
          nullable: true
        niche_class:
          type: array
          items:
            type: string
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        state:
          type: string
          nullable: true
        streamer:
          type: boolean
        userid:
          type: string
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        uses_link_in_bio:
          type: boolean
        video_content_creator:
          type: boolean
        audience:
          allOf:
            - $ref: '#/components/schemas/AudienceDataResponse'
          nullable: true
        brand_affinity:
          type: array
          items:
            $ref: '#/components/schemas/BrandAffinityResponse'
        brands_found:
          type: array
          items:
            type: object
            additionalProperties: {}
        comments_median:
          type: number
          format: double
          nullable: true
        creator_follower_growth:
          type: object
          nullable: true
          additionalProperties: {}
        has_merch:
          type: boolean
        hashtags:
          type: array
          items:
            type: string
        hashtags_count:
          type: array
          items:
            type: object
            additionalProperties: {}
        income:
          type: object
          nullable: true
          additionalProperties: {}
        likes_median:
          type: number
          format: double
          nullable: true
        locations:
          type: array
          items:
            type: string
        niche_sub_class:
          type: array
          items:
            type: string
        past_sponsors:
          type: array
          items:
            $ref: '#/components/schemas/PastSponsorResponse'
        posting_frequency_recent_months:
          type: number
          format: double
          nullable: true
        promotes_affiliate_links:
          type: boolean
        reels:
          type: object
          nullable: true
          additionalProperties: {}
        reels_percentage_last_12_posts:
          type: number
          format: double
          nullable: true
        sponsored_posts:
          type: array
          items:
            $ref: '#/components/schemas/SponsoredPostResponse'
        tagged:
          type: array
          items:
            type: object
            additionalProperties: {}
        post_data:
          type: object
          nullable: true
          additionalProperties: {}
    HandleFullLinkedinResponse:
      type: object
      properties:
        biography:
          type: string
          nullable: true
        connections:
          type: integer
          nullable: true
        first_name:
          type: string
          nullable: true
        follower_count:
          type: integer
          nullable: true
        full_name:
          type: string
          nullable: true
        hashtags:
          type: array
          items:
            type: string
        is_verified:
          type: boolean
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        posts:
          type: array
          items:
            type: object
            additionalProperties: {}
    HandleFullOnlyfansResponse:
      type: object
      properties:
        avg_comments:
          type: number
          format: double
          nullable: true
        avg_likes:
          type: number
          format: double
          nullable: true
        biography:
          type: string
          nullable: true
        can_chat:
          type: boolean
        can_create_promotion:
          type: boolean
        can_earn:
          type: boolean
        can_receive_chat_message:
          type: boolean
        country:
          type: string
          nullable: true
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        first_name:
          type: string
          nullable: true
        first_published_post_date:
          type: string
          nullable: true
        full_name:
          type: string
          nullable: true
        is_adult_content:
          type: boolean
        is_real_performer:
          type: boolean
        is_verified:
          type: boolean
        join_date:
          type: string
          nullable: true
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        linktree:
          type: string
          nullable: true
        location_source:
          type: array
          items:
            type: string
        media_count:
          type: integer
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        streamer:
          type: boolean
        subscribe_price:
          type: integer
          nullable: true
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        uses_link_in_bio:
          type: boolean
        archived_posts_count:
          type: integer
          nullable: true
        audios_count:
          type: integer
          nullable: true
        avg_durations:
          type: number
          format: double
          nullable: true
        comments_median:
          type: number
          format: double
          nullable: true
        finished_streams_count:
          type: integer
          nullable: true
        has_merch:
          type: boolean
        has_paid_partnership:
          type: boolean
        is_spotify_connected:
          type: boolean
        likes_median:
          type: number
          format: double
          nullable: true
        photos_count:
          type: integer
          nullable: true
        post_dates:
          type: array
          items:
            type: string
        post_durations:
          type: array
          items:
            type: number
            format: double
        posts_count:
          type: integer
          nullable: true
        private_archived_posts_count:
          type: integer
          nullable: true
        promotes_affiliate_links:
          type: boolean
        referal_bonus_sum_for_referer:
          type: integer
          nullable: true
        tips_enabled:
          type: boolean
        tips_max:
          type: integer
          nullable: true
        tips_min:
          type: integer
          nullable: true
        tips_min_internal:
          type: integer
          nullable: true
        tips_text_enabled:
          type: boolean
        total_likes:
          type: integer
          nullable: true
        videos_count:
          type: integer
          nullable: true
    HandleFullPinterestResponse:
      type: object
      properties:
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        pk:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        user_info:
          type: object
          nullable: true
          additionalProperties: {}
        user_media:
          type: object
          nullable: true
          additionalProperties: {}
    HandleFullPlatformResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/HandleFullResultResponse'
        credits_cost:
          type: number
          format: double
          nullable: true
          example: 1
    HandleFullResultResponse:
      type: object
      properties:
        age_group:
          type: object
          nullable: true
          additionalProperties: {}
        creator_has:
          type: object
          nullable: true
          additionalProperties: {}
        email:
          type: string
          format: email
          description: The creator's email address.
          nullable: true
        email_type:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        has_brand_deals:
          type: boolean
        has_link_in_bio:
          type: boolean
        instagram_link:
          type: string
          nullable: true
        is_business:
          type: boolean
        is_creator:
          type: boolean
        linkedin_link:
          type: string
          nullable: true
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        onlyfans_link:
          type: string
          nullable: true
        other_links:
          type: array
          items:
            type: string
        patreon_link:
          type: string
          nullable: true
        speaking_language:
          type: string
          nullable: true
        tiktok_link:
          type: string
          nullable: true
        twitch_link:
          type: string
          nullable: true
        twitter_link:
          type: string
          nullable: true
        youtube_link:
          type: string
          nullable: true
        instagram:
          $ref: '#/components/schemas/HandleFullInstagramResponse'
        youtube:
          $ref: '#/components/schemas/HandleFullYoutubeResponse'
        tiktok:
          $ref: '#/components/schemas/HandleFullTiktokResponse'
        onlyfans:
          $ref: '#/components/schemas/HandleFullOnlyfansResponse'
        twitter:
          $ref: '#/components/schemas/HandleFullTwitterResponse'
        twitch:
          $ref: '#/components/schemas/HandleFullTwitchResponse'
        linkedin:
          $ref: '#/components/schemas/HandleFullLinkedinResponse'
        facebook:
          $ref: '#/components/schemas/HandleFullFacebookResponse'
        pinterest:
          $ref: '#/components/schemas/HandleFullPinterestResponse'
        snapchat:
          $ref: '#/components/schemas/HandleProfileSnapchatResponse'
        discord:
          $ref: '#/components/schemas/HandleProfileDiscordResponse'
        audience_interests:
          type: array
          items:
            type: object
            additionalProperties: {}
        lookalikes:
          type: array
          items:
            type: object
            additionalProperties: {}
    HandleFullTiktokResponse:
      type: object
      properties:
        avg_likes:
          type: number
          format: double
          nullable: true
        biography:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        duet_setting:
          type: boolean
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        full_name:
          type: string
          nullable: true
        is_ad:
          type: boolean
        is_commerce:
          type: boolean
        is_private:
          type: boolean
        is_verified:
          type: boolean
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        mention_status:
          type: string
          nullable: true
        most_recent_post_date:
          type: string
          nullable: true
        niche_class:
          type: array
          items:
            type: string
        paid_partnership:
          type: boolean
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        region:
          type: string
          nullable: true
        sec_user_id:
          type: string
          nullable: true
        streamer:
          type: boolean
        tt_seller:
          type: boolean
          nullable: true
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        uses_link_in_bio:
          type: boolean
        video_count:
          type: integer
          nullable: true
        audience:
          allOf:
            - $ref: '#/components/schemas/AudienceDataResponse'
          nullable: true
        brands_found:
          type: array
          items:
            type: string
        challenges_list:
          type: array
          items:
            type: string
        comment_count_avg:
          type: number
          format: double
          nullable: true
        comments_median:
          type: number
          format: double
          nullable: true
        creator_follower_growth:
          type: object
          nullable: true
          additionalProperties: {}
        duration_avg:
          type: number
          format: double
          nullable: true
        has_merch:
          type: boolean
        hashtags:
          type: array
          items:
            type: string
        likes_median:
          type: number
          format: double
          nullable: true
        niche_sub_class:
          type: array
          items:
            type: string
        play_count_avg:
          type: number
          format: double
          nullable: true
        play_count_median:
          type: number
          format: double
          nullable: true
        posting_frequency:
          type: integer
          nullable: true
        posting_frequency_recent_months:
          type: number
          format: double
          nullable: true
        promotes_affiliate_links:
          type: boolean
        reach_score:
          type: number
          format: double
          nullable: true
        reach_score_list:
          type: array
          items:
            type: number
            format: double
        saves_count_list:
          type: array
          items:
            type: integer
        saves_median:
          type: number
          format: double
          nullable: true
        shares_median:
          type: number
          format: double
          nullable: true
        tagged:
          type: array
          items:
            type: string
        total_likes:
          type: integer
          nullable: true
        total_saves:
          type: integer
          nullable: true
        total_shares:
          type: integer
          nullable: true
        post_data:
          type: object
          nullable: true
          additionalProperties: {}
    HandleFullTwitchResponse:
      type: object
      properties:
        description:
          type: string
          nullable: true
        displayName:
          type: string
          nullable: true
        isPartner:
          type: boolean
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        other_links:
          type: array
          items:
            type: string
        panels_descriptions:
          type: array
          items:
            type: string
        panels_image:
          type: array
          items:
            type: string
        panels_titles:
          type: array
          items:
            type: string
        panels_type:
          type: array
          items:
            type: string
        panels_urls:
          type: array
          items:
            type: string
        profileImageURL:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        social_media:
          type: object
          nullable: true
          additionalProperties: {}
        total_followers:
          type: integer
          nullable: true
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        avg_views:
          type: number
          format: double
          nullable: true
        has_merch:
          type: boolean
        has_paid_partnership:
          type: boolean
        last_broadcast_game:
          type: string
          nullable: true
        last_broadcast_id:
          type: string
          nullable: true
        last_streamed:
          type: string
          nullable: true
        primary_team_display_name:
          type: string
          nullable: true
        primary_team_name:
          type: string
          nullable: true
        promotes_affiliate_links:
          type: boolean
        streamed_hours_last_30_days:
          type: number
          format: double
          nullable: true
        streams_count_last_30_days:
          type: integer
          nullable: true
        post_data:
          type: object
          nullable: true
          additionalProperties: {}
    HandleFullTwitterResponse:
      type: object
      properties:
        avg_likes:
          type: number
          format: double
          nullable: true
        biography:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        direct_messaging:
          type: boolean
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        full_name:
          type: string
          nullable: true
        is_verified:
          type: boolean
        join_date:
          type: string
          nullable: true
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        location_source:
          type: string
          nullable: true
        media_count:
          type: integer
          nullable: true
        most_recent_post_date:
          type: string
          nullable: true
        other_links:
          type: array
          items:
            type: string
        patreon:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        streamer:
          type: boolean
        subscriber_button:
          type: boolean
        super_followed_by:
          type: boolean
        userid:
          type: string
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        uses_link_in_bio:
          type: boolean
        avg_quotes:
          type: number
          format: double
          nullable: true
        avg_reply:
          type: number
          format: double
          nullable: true
        avg_retweet:
          type: number
          format: double
          nullable: true
        avg_views:
          type: number
          format: double
          nullable: true
        creator_favorite_count:
          type: integer
          nullable: true
        has_merch:
          type: boolean
        has_paid_partnership:
          type: boolean
        hashtags:
          type: array
          items:
            type: string
        languages_tweet:
          type: array
          items:
            type: string
        platforms:
          type: object
          nullable: true
          additionalProperties: {}
        promotes_affiliate_links:
          type: boolean
        recommended_users:
          type: array
          items:
            type: string
        retweet_users:
          type: array
          items:
            type: string
        retweets_count:
          type: array
          items:
            type: string
        tagged:
          type: array
          items:
            type: string
        tagged_usernames:
          type: array
          items:
            type: string
        tweets_count:
          type: integer
          nullable: true
        tweets_frequency_recent_months:
          type: number
          format: double
          nullable: true
        tweets_type:
          type: object
          nullable: true
          additionalProperties: {}
        post_data:
          type: object
          nullable: true
          additionalProperties: {}
        tweets:
          type: array
          items:
            type: string
    HandleFullYoutubeResponse:
      type: object
      properties:
        avg_comments:
          type: integer
          nullable: true
        avg_likes:
          type: number
          format: double
          nullable: true
        avg_views:
          type: number
          format: double
          nullable: true
        country:
          type: string
          nullable: true
        custom_url:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        first_name:
          type: string
          nullable: true
        has_community_posts:
          type: boolean
        has_paid_partnership:
          type: boolean
        has_shorts:
          type: boolean
        id:
          type: string
          nullable: true
        is_monetization_enabled:
          type: boolean
        is_verified:
          type: boolean
        language_code:
          type: array
          items:
            type: string
        link:
          type: string
          nullable: true
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        made_for_kids:
          type: boolean
        moderate_comments:
          type: boolean
        most_recent_post_date:
          type: string
          nullable: true
        niche_class:
          type: array
          items:
            type: string
        privacy_status:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        published_at:
          type: string
          nullable: true
        related_playlist_id:
          type: string
          nullable: true
        streamer:
          type: boolean
        subscriber_count:
          type: integer
          nullable: true
        title:
          type: string
          nullable: true
        unsubscribed_trailer_id:
          type: string
          nullable: true
        uses_link_in_bio:
          type: boolean
        video_count:
          type: integer
          nullable: true
        view_count:
          type: integer
          nullable: true
        audience:
          allOf:
            - $ref: '#/components/schemas/AudienceDataResponse'
          nullable: true
        avg_views_long:
          type: number
          format: double
          nullable: true
        avg_views_shorts:
          type: number
          format: double
          nullable: true
        engagement_by_comments_and_views_long:
          type: number
          format: double
          nullable: true
        engagement_by_comments_and_views_shorts:
          type: number
          format: double
          nullable: true
        engagement_by_likes_and_views_long:
          type: number
          format: double
          nullable: true
        engagement_by_likes_and_views_shorts:
          type: number
          format: double
          nullable: true
        engagement_by_views_and_subs_long:
          type: number
          format: double
          nullable: true
        engagement_by_views_and_subs_shorts:
          type: number
          format: double
          nullable: true
        engagement_percent_long:
          type: number
          format: double
          nullable: true
        engagement_percent_shorts:
          type: number
          format: double
          nullable: true
        hashtags_count:
          type: array
          items:
            type: object
            additionalProperties: {}
        income:
          type: object
          nullable: true
          additionalProperties: {}
        keywords:
          type: array
          items:
            type: string
        last_long_video_upload_date:
          type: string
          nullable: true
        last_short_video_upload_date:
          type: string
          nullable: true
        least_views:
          type: integer
          nullable: true
        median_views_long:
          type: number
          format: double
          nullable: true
        niche_sub_class:
          type: array
          items:
            type: string
        posting_frequency:
          type: number
          format: double
          nullable: true
        posting_frequency_long:
          type: number
          format: double
          nullable: true
        posting_frequency_recent_months:
          type: number
          format: double
          nullable: true
        posting_frequency_shorts:
          type: number
          format: double
          nullable: true
        posts_per_month:
          type: object
          nullable: true
          additionalProperties: {}
        promotes_affiliate_links:
          type: boolean
        shorts_percentage:
          type: number
          format: double
          nullable: true
        topic_details:
          type: array
          items:
            type: string
        total_comments_last_50:
          type: integer
          nullable: true
        video_categories:
          type: array
          items:
            type: string
        video_hashtags:
          type: array
          items:
            type: string
        video_tags:
          type: array
          items:
            type: string
        video_topics:
          type: array
          items:
            type: string
        post_data:
          type: object
          nullable: true
          additionalProperties: {}
    HandleProfileDiscordResponse:
      type: object
      properties:
        type:
          type: integer
          nullable: true
        code:
          type: string
          nullable: true
        id:
          type: integer
          nullable: true
        inviter:
          type: object
          nullable: true
          additionalProperties: {}
        expires_at:
          type: string
          nullable: true
        flags:
          type: integer
          nullable: true
        guild:
          type: object
          nullable: true
          additionalProperties: {}
        profile:
          type: object
          nullable: true
          additionalProperties: {}
        liveliness:
          type: object
          nullable: true
          additionalProperties: {}
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
    HandleProfileFacebookResponse:
      type: object
      properties:
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        user_info:
          type: object
          nullable: true
          additionalProperties: {}
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
    HandleProfileInstagramResponse:
      type: object
      properties:
        account_type:
          type: integer
          nullable: true
        avg_comments:
          type: number
          format: double
          nullable: true
        avg_likes:
          type: number
          format: double
          nullable: true
        biography:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        contact_phone_number:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        full_name:
          type: string
          nullable: true
        has_profile_pic:
          type: boolean
        is_business_account:
          type: boolean
        is_private:
          type: boolean
        is_verified:
          type: boolean
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        location_source:
          type: array
          items:
            type: string
        media_count:
          type: integer
          nullable: true
        most_recent_post_date:
          type: string
          nullable: true
        niche_class:
          type: array
          items:
            type: string
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        state:
          type: string
          nullable: true
        streamer:
          type: boolean
        userid:
          type: string
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        uses_link_in_bio:
          type: boolean
        video_content_creator:
          type: boolean
    HandleProfileLinkedinResponse:
      type: object
      properties:
        biography:
          type: string
          nullable: true
        connections:
          type: integer
          nullable: true
        first_name:
          type: string
          nullable: true
        follower_count:
          type: integer
          nullable: true
        full_name:
          type: string
          nullable: true
        hashtags:
          type: array
          items:
            type: string
        is_verified:
          type: boolean
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
    HandleProfileOnlyfansResponse:
      type: object
      properties:
        avg_comments:
          type: number
          format: double
          nullable: true
        avg_likes:
          type: number
          format: double
          nullable: true
        biography:
          type: string
          nullable: true
        can_chat:
          type: boolean
        can_create_promotion:
          type: boolean
        can_earn:
          type: boolean
        can_receive_chat_message:
          type: boolean
        country:
          type: string
          nullable: true
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        first_name:
          type: string
          nullable: true
        first_published_post_date:
          type: string
          nullable: true
        full_name:
          type: string
          nullable: true
        is_adult_content:
          type: boolean
        is_real_performer:
          type: boolean
        is_verified:
          type: boolean
        join_date:
          type: string
          nullable: true
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        linktree:
          type: string
          nullable: true
        location_source:
          type: array
          items:
            type: string
        media_count:
          type: integer
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        streamer:
          type: boolean
        subscribe_price:
          type: integer
          nullable: true
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        uses_link_in_bio:
          type: boolean
    HandleProfilePinterestResponse:
      type: object
      properties:
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        pk:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        user_info:
          type: object
          nullable: true
          additionalProperties: {}
    HandleProfilePlatformResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/HandleProfileResultResponse'
        credits_cost:
          type: number
          format: double
          nullable: true
          example: 0.2
    HandleProfileResultResponse:
      type: object
      properties:
        age_group:
          type: object
          nullable: true
          additionalProperties: {}
        creator_has:
          type: object
          nullable: true
          additionalProperties: {}
        email:
          type: string
          format: email
          description: The creator's email address.
          nullable: true
        email_type:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        has_brand_deals:
          type: boolean
        has_link_in_bio:
          type: boolean
        instagram_link:
          type: string
          nullable: true
        is_business:
          type: boolean
        is_creator:
          type: boolean
        linkedin_link:
          type: string
          nullable: true
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        onlyfans_link:
          type: string
          nullable: true
        other_links:
          type: array
          items:
            type: string
        patreon_link:
          type: string
          nullable: true
        speaking_language:
          type: string
          nullable: true
        tiktok_link:
          type: string
          nullable: true
        twitch_link:
          type: string
          nullable: true
        twitter_link:
          type: string
          nullable: true
        youtube_link:
          type: string
          nullable: true
        instagram:
          $ref: '#/components/schemas/HandleProfileInstagramResponse'
        youtube:
          $ref: '#/components/schemas/HandleProfileYoutubeResponse'
        tiktok:
          $ref: '#/components/schemas/HandleProfileTiktokResponse'
        onlyfans:
          $ref: '#/components/schemas/HandleProfileOnlyfansResponse'
        twitter:
          $ref: '#/components/schemas/HandleProfileTwitterResponse'
        twitch:
          $ref: '#/components/schemas/HandleProfileTwitchResponse'
        linkedin:
          $ref: '#/components/schemas/HandleProfileLinkedinResponse'
        facebook:
          $ref: '#/components/schemas/HandleProfileFacebookResponse'
        pinterest:
          $ref: '#/components/schemas/HandleProfilePinterestResponse'
        snapchat:
          $ref: '#/components/schemas/HandleProfileSnapchatResponse'
        discord:
          $ref: '#/components/schemas/HandleProfileDiscordResponse'
    HandleProfileSnapchatResponse:
      type: object
      properties:
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        is_private:
          type: boolean
        profile_picture_url:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        title:
          type: string
          nullable: true
        biography:
          type: string
          nullable: true
        subscriber_count:
          type: integer
          nullable: true
        address:
          type: string
          nullable: true
        has_curated_highlights:
          type: boolean
        has_spotlight_highlights:
          type: boolean
        page_description:
          type: string
          nullable: true
        curated_highlights_story_titles:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        other_links:
          type: array
          items:
            type: string
    HandleProfileTiktokResponse:
      type: object
      properties:
        avg_likes:
          type: number
          format: double
          nullable: true
        biography:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        duet_setting:
          type: boolean
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        full_name:
          type: string
          nullable: true
        is_ad:
          type: boolean
        is_commerce:
          type: boolean
        is_private:
          type: boolean
        is_verified:
          type: boolean
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        mention_status:
          type: string
          nullable: true
        most_recent_post_date:
          type: string
          nullable: true
        niche_class:
          type: array
          items:
            type: string
        paid_partnership:
          type: boolean
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        region:
          type: string
          nullable: true
        sec_user_id:
          type: string
          nullable: true
        streamer:
          type: boolean
        tt_seller:
          type: boolean
          nullable: true
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        uses_link_in_bio:
          type: boolean
        video_count:
          type: integer
          nullable: true
    HandleProfileTwitchResponse:
      type: object
      properties:
        description:
          type: string
          nullable: true
        displayName:
          type: string
          nullable: true
        isPartner:
          type: boolean
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        other_links:
          type: array
          items:
            type: string
        panels_descriptions:
          type: array
          items:
            type: string
        panels_image:
          type: array
          items:
            type: string
        panels_titles:
          type: array
          items:
            type: string
        panels_type:
          type: array
          items:
            type: string
        panels_urls:
          type: array
          items:
            type: string
        profileImageURL:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        social_media:
          type: object
          nullable: true
          additionalProperties: {}
        total_followers:
          type: integer
          nullable: true
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
    HandleProfileTwitterResponse:
      type: object
      properties:
        avg_likes:
          type: number
          format: double
          nullable: true
        biography:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        direct_messaging:
          type: boolean
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        full_name:
          type: string
          nullable: true
        is_verified:
          type: boolean
        join_date:
          type: string
          nullable: true
        language_code:
          type: array
          items:
            type: string
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        location_source:
          type: string
          nullable: true
        media_count:
          type: integer
          nullable: true
        most_recent_post_date:
          type: string
          nullable: true
        other_links:
          type: array
          items:
            type: string
        patreon:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        streamer:
          type: boolean
        subscriber_button:
          type: boolean
        super_followed_by:
          type: boolean
        userid:
          type: string
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        uses_link_in_bio:
          type: boolean
    HandleProfileYoutubeResponse:
      type: object
      properties:
        avg_comments:
          type: integer
          nullable: true
        avg_likes:
          type: number
          format: double
          nullable: true
        avg_views:
          type: number
          format: double
          nullable: true
        country:
          type: string
          nullable: true
        custom_url:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        engagement_percent:
          type: number
          format: double
          nullable: true
        exists:
          type: boolean
        first_name:
          type: string
          nullable: true
        has_community_posts:
          type: boolean
        has_paid_partnership:
          type: boolean
        has_shorts:
          type: boolean
        id:
          type: string
          nullable: true
        is_monetization_enabled:
          type: boolean
        is_verified:
          type: boolean
        language_code:
          type: array
          items:
            type: string
        link:
          type: string
          nullable: true
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        made_for_kids:
          type: boolean
        moderate_comments:
          type: boolean
        most_recent_post_date:
          type: string
          nullable: true
        niche_class:
          type: array
          items:
            type: string
        privacy_status:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        published_at:
          type: string
          nullable: true
        related_playlist_id:
          type: string
          nullable: true
        streamer:
          type: boolean
        subscriber_count:
          type: integer
          nullable: true
        title:
          type: string
          nullable: true
        unsubscribed_trailer_id:
          type: string
          nullable: true
        uses_link_in_bio:
          type: boolean
        video_count:
          type: integer
          nullable: true
        view_count:
          type: integer
          nullable: true
    HandleRawDiscordResponse:
      type: object
      properties:
        type:
          type: string
          nullable: true
        code:
          type: string
          nullable: true
        inviter:
          type: object
          additionalProperties: {}
        expires_at:
          type: string
          nullable: true
        flags:
          type: integer
          nullable: true
        guild:
          type: object
          additionalProperties: {}
        profile:
          type: object
          additionalProperties: {}
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
      required:
        - inviter
        - guild
        - profile
    HandleRawFacebookResponse:
      type: object
      properties:
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        user_info:
          type: object
          additionalProperties: {}
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        post_data:
          type: array
          items:
            type: string
      required:
        - user_info
        - post_data
    HandleRawInstagramResponse:
      type: object
      properties:
        userid:
          type: string
          nullable: true
        exists:
          type: boolean
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        has_profile_pic:
          type: boolean
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        biography:
          type: string
          nullable: true
        full_name:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        media_count:
          type: integer
          nullable: true
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        is_private:
          type: boolean
          nullable: true
        is_business_account:
          type: boolean
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        video_content_creator:
          type: boolean
          nullable: true
        uses_link_in_bio:
          type: boolean
          nullable: true
        links_in_bio:
          type: array
          items:
            type: string
        post_data:
          type: array
          items:
            type: string
      required:
        - links_in_bio
        - post_data
    HandleRawLinkedInResponse:
      type: object
      properties:
        id:
          type: string
          nullable: true
        connection:
          type: string
          nullable: true
        followers:
          type: integer
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        is_creator:
          type: boolean
          nullable: true
        is_premium:
          type: boolean
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_pictures:
          type: array
          items:
            type: string
        background_image:
          type: string
          nullable: true
        summary:
          type: string
          nullable: true
        headline:
          type: string
          nullable: true
        geo:
          type: object
          additionalProperties: {}
        position:
          type: object
          additionalProperties: {}
        full_positions:
          type: array
          items:
            type: string
        skills:
          type: array
          items:
            type: string
        projects:
          type: array
          items:
            type: string
        supported_locales:
          type: array
          items:
            type: string
        multi_locale_first_name:
          type: object
          additionalProperties: {}
        multi_locale_last_name:
          type: object
          additionalProperties: {}
        multi_locale_headline:
          type: object
          additionalProperties: {}
      required:
        - profile_pictures
        - geo
        - position
        - full_positions
        - skills
        - projects
        - supported_locales
        - multi_locale_first_name
        - multi_locale_last_name
        - multi_locale_headline
    HandleRawOnlyFansResponse:
      type: object
      properties:
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        exists:
          type: boolean
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        full_name:
          type: string
          nullable: true
        biography:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        subscribe_price:
          type: number
          format: double
          nullable: true
        join_date:
          type: string
          nullable: true
        first_published_post_date:
          type: string
          nullable: true
        last_seen:
          type: string
          nullable: true
        wishlist:
          type: array
          items:
            type: string
        posts_count:
          type: integer
          nullable: true
        photos_count:
          type: integer
          nullable: true
        videos_count:
          type: integer
          nullable: true
        audios_count:
          type: integer
          nullable: true
        media_count:
          type: integer
          nullable: true
        total_likes:
          type: integer
          nullable: true
        is_real_performer:
          type: boolean
          nullable: true
        is_adult_content:
          type: boolean
          nullable: true
        finished_streams_count:
          type: integer
          nullable: true
        can_create_promotion:
          type: boolean
          nullable: true
        tips_enabled:
          type: boolean
          nullable: true
        tips_text_enabled:
          type: boolean
          nullable: true
        tips_min:
          type: number
          format: double
          nullable: true
        tips_min_internal:
          type: number
          format: double
          nullable: true
        tips_max:
          type: number
          format: double
          nullable: true
        can_earn:
          type: boolean
          nullable: true
        archived_posts_count:
          type: integer
          nullable: true
        private_archived_posts_count:
          type: integer
          nullable: true
        is_spotify_connected:
          type: boolean
          nullable: true
        referal_bonus_sum_for_referer:
          type: number
          format: double
          nullable: true
        can_receive_chat_message:
          type: boolean
          nullable: true
        can_chat:
          type: boolean
          nullable: true
        post_dates:
          type: array
          items:
            type: string
        post_data:
          type: array
          items:
            type: string
      required:
        - wishlist
        - post_dates
        - post_data
    HandleRawPinterestResponse:
      type: object
      properties:
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        pk:
          type: string
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        user_info:
          type: object
          additionalProperties: {}
      required:
        - user_info
    HandleRawPlatformResponse:
      type: object
      properties:
        credits_cost:
          type: number
          format: double
          nullable: true
          example: 0.03
        result:
          $ref: '#/components/schemas/HandleRawResultResponse'
    HandleRawRedditResponse:
      type: object
      properties:
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        pk:
          type: string
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        user_info:
          type: object
          additionalProperties: {}
      required:
        - user_info
    HandleRawResultResponse:
      type: object
      properties:
        twitter:
          $ref: '#/components/schemas/HandleRawTwitterResponse'
        twitch:
          $ref: '#/components/schemas/HandleRawTwitchResponse'
        onlyfans:
          $ref: '#/components/schemas/HandleRawOnlyFansResponse'
        youtube:
          $ref: '#/components/schemas/HandleRawYouTubeResponse'
        tiktok:
          $ref: '#/components/schemas/HandleRawTikTokResponse'
        instagram:
          $ref: '#/components/schemas/HandleRawInstagramResponse'
        facebook:
          $ref: '#/components/schemas/HandleRawFacebookResponse'
        pinterest:
          $ref: '#/components/schemas/HandleRawPinterestResponse'
        reddit:
          $ref: '#/components/schemas/HandleRawRedditResponse'
        snapchat:
          $ref: '#/components/schemas/HandleRawSnapchatResponse'
        discord:
          $ref: '#/components/schemas/HandleRawDiscordResponse'
        linkedin:
          $ref: '#/components/schemas/HandleRawLinkedInResponse'
    HandleRawSnapchatResponse:
      type: object
      properties:
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        is_private:
          type: boolean
          nullable: true
        profile_picture_url:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        title:
          type: string
          nullable: true
        biography:
          type: string
          nullable: true
        subscriber_count:
          type: integer
          nullable: true
        address:
          type: string
          nullable: true
        has_curated_highlights:
          type: boolean
          nullable: true
        has_spotlight_highlights:
          type: boolean
          nullable: true
        page_description:
          type: string
          nullable: true
        links_in_bio:
          type: array
          items:
            type: string
      required:
        - links_in_bio
    HandleRawTikTokResponse:
      type: object
      properties:
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        sec_user_id:
          type: string
          nullable: true
        exists:
          type: boolean
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        full_name:
          type: string
          nullable: true
        biography:
          type: string
          nullable: true
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        video_count:
          type: integer
          nullable: true
        total_likes:
          type: integer
          nullable: true
        total_shares:
          type: integer
          nullable: true
        total_saves:
          type: integer
          nullable: true
        links_in_bio:
          type: array
          items:
            type: string
        tt_seller:
          type: boolean
          nullable: true
        is_ad:
          type: boolean
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        is_commerce:
          type: boolean
          nullable: true
        duet_setting:
          type: string
          nullable: true
        is_private:
          type: boolean
          nullable: true
        saves_count_list:
          type: array
          items:
            type: string
        post_data:
          type: array
          items:
            type: string
      required:
        - links_in_bio
        - saves_count_list
        - post_data
    HandleRawTwitchResponse:
      type: object
      properties:
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        profileImageURL:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        description:
          type: string
          nullable: true
        displayName:
          type: string
          nullable: true
        total_followers:
          type: integer
          nullable: true
        twitch_tracker_data:
          type: object
          additionalProperties: {}
        links_in_bio:
          type: array
          items:
            type: string
        post_data:
          type: array
          items:
            type: string
      required:
        - twitch_tracker_data
        - links_in_bio
        - post_data
    HandleRawTwitterResponse:
      type: object
      properties:
        userid:
          type: string
          nullable: true
        exists:
          type: boolean
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        full_name:
          type: string
          nullable: true
        biography:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        join_date:
          type: string
          nullable: true
        links_in_bio:
          type: array
          items:
            type: string
        location:
          type: string
          nullable: true
        follower_count:
          type: integer
          nullable: true
        following_count:
          type: integer
          nullable: true
        media_count:
          type: integer
          nullable: true
        tweets_count:
          type: integer
          nullable: true
        creator_favorite_count:
          type: integer
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        direct_messaging:
          type: boolean
          nullable: true
        subscriber_button:
          type: boolean
          nullable: true
        super_followed_by:
          type: boolean
          nullable: true
        tweets_type:
          type: object
          additionalProperties: {}
        post_data:
          type: array
          items:
            type: string
      required:
        - links_in_bio
        - tweets_type
        - post_data
    HandleRawYouTubeResponse:
      type: object
      properties:
        id:
          type: string
          nullable: true
        exists:
          type: boolean
          nullable: true
        link:
          type: string
          nullable: true
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        related_playlist_id:
          type: string
          nullable: true
        profile_picture_hd:
          type: string
          description: >-
            URL to the creator's high-definition profile picture. This URL is
            temporary and expires after 24 hours. To keep the image, download it
            to your own storage before it expires.
          nullable: true
        custom_url:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        published_at:
          type: string
          nullable: true
        subscriber_count:
          type: integer
          nullable: true
        video_count:
          type: integer
          nullable: true
        view_count:
          type: integer
          nullable: true
        country:
          type: string
          nullable: true
        has_shorts:
          type: boolean
          nullable: true
        has_community_posts:
          type: boolean
          nullable: true
        made_for_kids:
          type: boolean
          nullable: true
        privacy_status:
          type: string
          nullable: true
        moderate_comments:
          type: boolean
          nullable: true
        unsubscribed_trailer_id:
          type: string
          nullable: true
        total_comments_last_50:
          type: integer
          nullable: true
        topic_details:
          type: array
          items:
            type: string
        post_data:
          type: array
          items:
            type: string
      required:
        - topic_details
        - post_data
    ImageVersionsModel:
      type: object
      properties:
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/MediaCandidateModel'
      required:
        - candidates
    InstagramDiscoveryFilters:
      type: object
      properties:
        location:
          type: array
          items:
            type: string
            nullable: true
        type:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        profile_language:
          type: array
          items:
            type: string
            nullable: true
        ai_search:
          type: string
          description: >-
            Finds creators matching a single niche (e.g., 'plant-based
            recipes'), 3-150 characters; only letters, numbers and # - / , . ! ?
            + are supported. For best results, use one niche at a time—long or
            multi-topic phrases return weaker matches.
          nullable: true
        keywords_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        exclude_keywords_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_in_captions:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_not_in_captions:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        number_of_followers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        engagement_percent:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_likes:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_comments:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        number_of_posts:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        reels_percent:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_views_for_reels:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        posting_frequency:
          type: number
          format: double
          nullable: true
        follower_growth:
          allOf:
            - $ref: '#/components/schemas/GrowthRequest'
          nullable: true
        income:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        last_post:
          type: string
          description: 'Allowed values: any, 90, 365'
          nullable: true
        has_videos:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        exclude_private_profile:
          type: boolean
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        audience:
          allOf:
            - $ref: '#/components/schemas/AudienceFilterRequest'
          nullable: true
        creator_has:
          $ref: '#/components/schemas/CreatorHasRequest'
        promotes_affiliate_links:
          type: boolean
          nullable: true
        has_done_brand_deals:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        has_link_in_bio:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        does_live_streaming:
          type: boolean
          nullable: true
        has_merch:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        exclude_role_based_emails:
          type: boolean
          nullable: true
          default: false
        exclude_handles:
          type: array
          items:
            type: string
        exclude_list:
          type: array
          items:
            type: integer
          description: >-
            IDs of exclusion lists to apply. Create and manage these via the
            Exclusion lists endpoints, then pass their IDs here; only lists for
            this platform are applied.
        exclude_default_list:
          type: boolean
          description: >-
            When true, applies the team's default exclusion list for this
            platform.
          default: false
        exclude_all_lists:
          type: boolean
          description: >-
            When true, applies every exclusion list for this platform (the
            default list and all specific lists).
          default: false
    Language:
      type: object
      properties:
        language:
          type: string
        abbreviation:
          type: string
      required:
        - language
        - abbreviation
    MatchedFilters:
      type: object
      properties:
        audience_location:
          type: array
          items:
            type: string
          description: Echoed location conditions, e.g. ["US>30%"].
        audience_gender:
          type: string
          description: Echoed gender condition, e.g. "female>60%".
        audience_age:
          type: array
          items:
            type: string
          description: Echoed age conditions, e.g. ["18-24>40%"].
        audience_interests:
          type: array
          items:
            type: string
          description: Echoed interest conditions.
        audience_language:
          type: array
          items:
            type: string
          description: Echoed language conditions.
        audience_credibility:
          type: string
          description: Echoed audience credibility class.
        creator_has:
          $ref: '#/components/schemas/CreatorHas'
          description: Requested networks/links that matched (true entries only).
        has_brand_deals:
          type: boolean
          description: Echoes the has_done_brand_deals filter you sent.
        has_link_in_bio:
          type: boolean
          description: Echoes the has_link_in_bio filter you sent.
        has_merch:
          type: boolean
          description: Echoes the has_merch filter you sent.
        has_affiliate_links:
          type: boolean
          description: Echoes the promotes_affiliate_links filter you sent.
        hashtags:
          type: array
          items:
            type: string
          description: The hashtags you searched for.
        not_hashtags:
          type: array
          items:
            type: string
          description: The excluded hashtags you searched for.
        posting_frequency:
          type: number
          format: double
          description: The creator's resolved posting frequency (posts per month).
        creator_growth:
          type: number
          format: double
          description: The creator's resolved growth percentage for the requested window.
        income:
          $ref: '#/components/schemas/Range'
          description: The creator's resolved income range (rounded to hundreds).
        ai_search:
          type: string
          description: Echoes the ai_search filter you sent.
        average_comments:
          type: number
          format: double
          description: The creator's resolved average comments per post.
        average_likes:
          type: number
          format: double
          description: The creator's resolved average likes per post.
        average_stream_duration:
          type: number
          format: double
          description: The creator's resolved average stream duration.
        average_stream_views:
          type: number
          format: double
          description: The creator's resolved average stream views.
        average_video_downloads:
          type: number
          format: double
          description: The creator's resolved average downloads per video.
        average_views:
          type: number
          format: double
          description: The creator's resolved average views per video.
        average_views_for_reels:
          type: number
          format: double
          description: The creator's resolved average views on reels.
        average_views_on_long_videos:
          type: number
          format: double
          description: The creator's resolved average views on long-form videos.
        average_views_on_shorts:
          type: number
          format: double
          description: The creator's resolved average views on Shorts.
        avg_views_last_30_days:
          type: number
          format: double
          description: The creator's resolved average views over the last 30 days.
        brands:
          type: array
          items:
            type: string
          description: Echoes the brands values you sent.
        does_live_streaming:
          type: boolean
          description: Echoes the does_live_streaming filter you sent.
        engagement_percent:
          type: number
          format: double
          description: The creator's resolved engagement percentage.
        exclude_keywords_in_bio:
          type: array
          items:
            type: string
          description: Echoes the exclude_keywords_in_bio values you sent.
        exclude_private_profile:
          type: boolean
          description: Echoes the exclude_private_profile filter you sent.
        exclude_role_based_emails:
          type: boolean
          description: Echoes the exclude_role_based_emails filter you sent.
        followers:
          type: integer
          description: The creator's resolved follower count.
        games_played:
          type: array
          items:
            type: string
          description: Echoes the games_played values you sent.
        gender:
          type: string
          description: Echoes the gender filter you sent.
        has_community_posts:
          type: boolean
          description: Echoes the has_community_posts filter you sent.
        has_courses:
          type: boolean
          description: Echoes the has_courses filter you sent.
        has_free_account:
          type: boolean
          description: Echoes the has_free_account filter you sent.
        has_live_streams:
          type: boolean
          description: Echoes the has_live_streams filter you sent.
        has_membership:
          type: boolean
          description: Echoes the has_membership filter you sent.
        has_podcast:
          type: boolean
          description: Echoes the has_podcast filter you sent.
        has_shorts:
          type: boolean
          description: Echoes the has_shorts filter you sent.
        has_tik_tok_shop:
          type: boolean
          description: Echoes the has_tik_tok_shop filter you sent.
        has_videos:
          type: boolean
          description: Echoes the has_videos filter you sent.
        is_monetizing:
          type: boolean
          description: Echoes the is_monetizing filter you sent.
        is_twitch_partner:
          type: boolean
          description: Echoes the is_twitch_partner filter you sent.
        is_verified:
          type: boolean
          description: Echoes the is_verified filter you sent.
        keywords_in_bio:
          type: array
          items:
            type: string
          description: Echoes the keywords_in_bio values you sent.
        keywords_in_captions:
          type: array
          items:
            type: string
          description: Echoes the keywords_in_captions values you sent.
        keywords_in_description:
          type: array
          items:
            type: string
          description: Echoes the keywords_in_description values you sent.
        keywords_in_tweets:
          type: array
          items:
            type: string
          description: Echoes the keywords_in_tweets values you sent.
        keywords_in_video_description:
          type: array
          items:
            type: string
          description: Echoes the keywords_in_video_description values you sent.
        keywords_in_video_titles:
          type: array
          items:
            type: string
          description: Echoes the keywords_in_video_titles values you sent.
        keywords_not_in_captions:
          type: array
          items:
            type: string
          description: Echoes the keywords_not_in_captions values you sent.
        keywords_not_in_description:
          type: array
          items:
            type: string
          description: Echoes the keywords_not_in_description values you sent.
        keywords_not_in_tweets:
          type: array
          items:
            type: string
          description: Echoes the keywords_not_in_tweets values you sent.
        keywords_not_in_video_description:
          type: array
          items:
            type: string
          description: Echoes the keywords_not_in_video_description values you sent.
        keywords_not_in_video_titles:
          type: array
          items:
            type: string
          description: Echoes the keywords_not_in_video_titles values you sent.
        last_active:
          type: string
          description: The creator's resolved last-active date.
        last_post:
          type: string
          description: The creator's resolved most recent post date.
        last_stream_upload:
          type: string
          description: The creator's resolved last stream upload date.
        last_upload_long_video:
          type: string
          description: The creator's resolved last long-form video upload date.
        last_upload_short_video:
          type: string
          description: The creator's resolved last short-form video upload date.
        link_in_bio:
          type: array
          items:
            type: string
          description: Echoes the link_in_bio values you sent.
        links_from_description:
          type: array
          items:
            type: string
          description: Echoes the links_from_description values you sent.
        links_from_video_description:
          type: array
          items:
            type: string
          description: Echoes the links_from_video_description values you sent.
        location:
          type: array
          items:
            type: string
          description: Echoes the location values you sent.
        long_video_duration:
          $ref: '#/components/schemas/Range'
          description: Echoes the long_video_duration range you sent.
        maximum_views_count:
          type: number
          format: double
          description: The creator's resolved maximum views on a stream.
        most_recent_stream_date:
          type: string
          description: The creator's resolved most recent stream date.
        not_link_in_bio:
          type: array
          items:
            type: string
          description: Echoes the not_link_in_bio values you sent.
        not_video_description:
          type: array
          items:
            type: string
          description: Echoes the not_video_description values you sent.
        number_of_followers:
          type: integer
          description: The creator's resolved follower count.
        number_of_likes:
          type: integer
          description: The creator's resolved total likes.
        number_of_photos:
          type: number
          format: double
          description: >-
            The creator's resolved media count (matches what the filter ranges
            on; includes videos, not photos only).
        number_of_posts:
          type: number
          format: double
          description: The creator's resolved number of posts.
        number_of_subscribers:
          type: integer
          description: The creator's resolved subscriber count.
        number_of_videos:
          type: integer
          description: The creator's resolved video count.
        profile_language:
          type: array
          items:
            type: string
          description: Echoes the profile_language values you sent.
        reels_percent:
          type: number
          format: double
          description: The creator's resolved percentage of posts that are reels.
        shorts_percentage:
          type: number
          format: double
          description: The creator's resolved percentage of uploads that are Shorts.
        streamed_hours_last_30_days:
          type: number
          format: double
          description: The creator's resolved hours streamed over the last 30 days.
        streams_count_last_30_days:
          type: number
          format: double
          description: The creator's resolved stream count over the last 30 days.
        streams_live:
          type: boolean
          description: Echoes the streams_live filter you sent.
        subscription_price:
          type: number
          format: double
          description: The creator's resolved subscription price.
        topics:
          type: array
          items:
            type: string
          description: Echoes the topics values you sent.
        tweets_count:
          type: number
          format: double
          description: The creator's resolved tweet count.
        type:
          type: string
          description: Echoes the type filter you sent.
        video_count:
          type: integer
          description: The creator's resolved video count.
        video_description:
          type: array
          items:
            type: string
          description: Echoes the video_description values you sent.
    MediaCandidateModel:
      type: object
      properties:
        url:
          type: string
          description: The creator's profile URL.
          nullable: true
        width:
          type: integer
          nullable: true
        height:
          type: integer
          nullable: true
    NlpSearchEcho:
      type: object
      properties:
        from_nlp:
          type: object
          description: The filters the AI inferred from the brief.
          additionalProperties: {}
        overridden_by_user:
          type: array
          items:
            type: string
          description: Fields where your explicit value beat the AI's inference.
        notes:
          type: array
          items:
            type: string
          description: >-
            Human-readable reasons a filter wasn't applied, e.g. unavailable on
            this platform.
    NotifyEndpoint:
      type: object
      properties:
        id:
          type: integer
          description: Notify endpoint identifier.
        destination:
          type: string
          description: Delivery destination (e.g. the webhook URL).
        notify_type:
          type: string
          description: Delivery type of the endpoint (e.g. 'api').
        created_at:
          type: string
          format: date-time
          description: When the endpoint was created.
      required:
        - id
        - destination
        - notify_type
        - created_at
    NotifyEndpointInput:
      type: object
      properties:
        id:
          type: integer
          description: >-
            ID of an existing notify endpoint. Mutually exclusive with
            'destination'.
        destination:
          type: string
          description: >-
            Destination for a new inline endpoint (e.g. a webhook URL). Mutually
            exclusive with 'id'.
        notify_type:
          type: string
          description: Delivery type for a new inline endpoint. Defaults to 'api'.
          default: api
    OnlyFansDiscoveryFilters:
      type: object
      properties:
        location:
          type: array
          items:
            type: string
            nullable: true
        gender:
          type: string
          nullable: true
        profile_language:
          type: array
          items:
            type: string
            nullable: true
        ai_search:
          type: string
          description: >-
            Finds creators matching a single niche (e.g., 'plant-based
            recipes'), 3-150 characters; only letters, numbers and # - / , . ! ?
            + are supported. For best results, use one niche at a time—long or
            multi-topic phrases return weaker matches.
          nullable: true
        number_of_likes:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        number_of_photos:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        subscription_price:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        has_videos:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        has_free_account:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        has_live_streams:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        last_active:
          type: string
          description: 'Allowed values: any, 90, 365'
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        creator_has:
          $ref: '#/components/schemas/CreatorHasRequest'
        promotes_affiliate_links:
          type: boolean
          nullable: true
        has_done_brand_deals:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        has_link_in_bio:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        does_live_streaming:
          type: boolean
          nullable: true
        has_merch:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        exclude_role_based_emails:
          type: boolean
          nullable: true
          default: false
        exclude_handles:
          type: array
          items:
            type: string
        exclude_list:
          type: array
          items:
            type: integer
          description: >-
            IDs of exclusion lists to apply. Create and manage these via the
            Exclusion lists endpoints, then pass their IDs here; only lists for
            this platform are applied.
        exclude_default_list:
          type: boolean
          description: >-
            When true, applies the team's default exclusion list for this
            platform.
          default: false
        exclude_all_lists:
          type: boolean
          description: >-
            When true, applies every exclusion list for this platform (the
            default list and all specific lists).
          default: false
    OverlapDataItem:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/OverlapUser'
        user_id:
          type: string
          description: The creator's unique platform identifier.
        username:
          type: string
          description: The creator's username on the platform.
        followers:
          type: integer
        unique_percentage:
          type: number
          format: double
        overlapping_percentage:
          type: number
          format: double
      required:
        - user
        - user_id
        - username
        - followers
        - unique_percentage
        - overlapping_percentage
    OverlapUser:
      type: object
      properties:
        user_id:
          type: string
          description: The creator's unique platform identifier.
          nullable: true
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        followers:
          type: integer
          nullable: true
        fullname:
          type: string
          nullable: true
        url:
          type: string
          description: The creator's profile URL.
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        engagements:
          type: integer
          nullable: true
        stats:
          type: array
          items:
            $ref: '#/components/schemas/OverlapUserStats'
    OverlapUserStats:
      type: object
      properties:
        post_type:
          type: string
          nullable: true
        engagements:
          type: integer
          nullable: true
    Paging:
      type: object
      properties:
        limit:
          type: integer
        page:
          type: integer
          description: Page number (0-indexed). The first page is 0, not 1.
      required:
        - limit
        - page
    PagingRequest:
      type: object
      properties:
        limit:
          type: integer
        page:
          type: integer
          description: Page number (0-indexed). The first page is 0, not 1.
      required:
        - limit
        - page
    PastSponsorResponse:
      type: object
      properties:
        handle:
          type: string
          description: Handle of the mentioned sponsor.
          nullable: true
        post_count:
          type: integer
          description: Number of sponsored posts mentioning this handle.
        first_seen:
          type: string
          description: >-
            Timestamp of the earliest sponsored post mentioning this handle, in
            ISO 8601 format.
          nullable: true
        last_seen:
          type: string
          description: >-
            Timestamp of the most recent sponsored post mentioning this handle,
            in ISO 8601 format.
          nullable: true
        post_ids:
          type: array
          items:
            type: string
          description: IDs of the sponsored posts mentioning this handle.
    PostItemModel:
      type: object
      properties:
        pk:
          type: string
        taken_at:
          type: integer
          nullable: true
        url:
          type: string
          description: The creator's profile URL.
          nullable: true
        device_timestamp:
          type: integer
          nullable: true
        media_url:
          type: string
          nullable: true
        media_id:
          type: string
          nullable: true
        image_versions:
          $ref: '#/components/schemas/ImageVersionsModel'
        media_type:
          type: integer
        user:
          $ref: '#/components/schemas/UserInfoModel'
        engagement:
          $ref: '#/components/schemas/EngagementModel'
        caption:
          type: string
          nullable: true
        thumbnails:
          type: object
          nullable: true
          additionalProperties: {}
      required:
        - pk
        - image_versions
        - media_type
        - user
        - engagement
    PublicAPIInstagramAudience:
      type: object
      properties:
        location:
          type: array
          items:
            $ref: '#/components/schemas/AudienceLocation'
          nullable: true
        gender:
          allOf:
            - $ref: '#/components/schemas/AudienceGender'
          nullable: true
        language:
          type: array
          items:
            $ref: '#/components/schemas/AudienceLanguage'
          nullable: true
        age:
          type: array
          items:
            $ref: '#/components/schemas/AudienceAge'
          nullable: true
        interests:
          type: array
          items:
            $ref: '#/components/schemas/AudienceInterest'
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        brand_categories:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        credibility:
          type: string
          enum:
            - bad
            - low
            - normal
            - good
            - high
            - best
          nullable: true
    Range:
      type: object
      properties:
        min:
          type: number
          format: double
          nullable: true
        max:
          type: number
          format: double
          nullable: true
    RangeRequest:
      type: object
      properties:
        min:
          type: number
          format: double
          nullable: true
        max:
          type: number
          format: double
          nullable: true
    RegisterClientRequest:
      type: object
      properties:
        client_name:
          type: string
          description: Human-readable name of the client application.
        redirect_uris:
          type: array
          items:
            type: string
          description: >-
            List of allowed redirect URIs. At least one is required. The
            redirect_uri used in the authorization request must exactly match
            one of these.
        scope:
          type: string
          description: >-
            Space-separated list of requested scopes. Available value: `all`.
            Defaults to `all` if omitted.
          default: all
      required:
        - client_name
        - redirect_uris
    RegisterClientResponse:
      type: object
      properties:
        client_id:
          type: string
          description: >-
            Unique identifier for the registered client. Persist this value — it
            is required for all subsequent authorization requests.
        client_name:
          type: string
          description: Human-readable name of the client application.
        redirect_uris:
          type: array
          items:
            type: string
          description: Registered redirect URIs for this client.
        scope:
          type: string
          description: Space-separated list of scopes granted to this client.
        token_endpoint_auth_method:
          type: string
          description: >-
            Authentication method for the token endpoint. Always `none` (public
            client, PKCE required).
        grant_types:
          type: array
          items:
            type: string
          description: Supported grant types. Always `[authorization_code, refresh_token]`.
        response_types:
          type: array
          items:
            type: string
          description: Supported response types. Always `[code]`.
        client_id_issued_at:
          type: integer
          description: Unix timestamp of when the client_id was issued.
      required:
        - client_id
        - client_name
        - redirect_uris
        - scope
        - token_endpoint_auth_method
        - grant_types
        - response_types
        - client_id_issued_at
    RemoveCampaignCreatorsInput:
      type: object
      properties:
        creator_ids:
          type: array
          items:
            type: integer
          description: >-
            IDs of the campaign creator links to remove, as returned in the
            campaign Creators list ('id').
      required:
        - creator_ids
    RemoveCampaignCreatorsInputRequest:
      type: object
      properties:
        creator_ids:
          type: array
          items:
            type: integer
          description: >-
            IDs of the campaign creator links to remove, as returned in the
            campaign Creators list ('id').
      required:
        - creator_ids
    ReportInfo:
      type: object
      properties:
        total_followers:
          type: integer
          nullable: true
        total_unique_followers:
          type: integer
          nullable: true
    SimilarCreatorsInstagramRequest:
      type: object
      required:
        - filter_key
        - filter_value
        - paging
      properties:
        platform:
          type: string
          enum:
            - instagram
        filter_key:
          type: string
          enum:
            - url
            - username
            - id
        filter_value:
          type: string
          description: Email, platform url or profile handle
        paging:
          $ref: '#/components/schemas/PagingRequest'
        filters:
          $ref: '#/components/schemas/InstagramDiscoveryFilters'
    SimilarCreatorsOnlyFansRequest:
      type: object
      required:
        - filter_key
        - filter_value
        - paging
      properties:
        platform:
          type: string
          enum:
            - onlyfans
        filter_key:
          type: string
          enum:
            - url
            - username
            - id
        filter_value:
          type: string
          description: Email, platform url or profile handle
        paging:
          $ref: '#/components/schemas/PagingRequest'
        filters:
          $ref: '#/components/schemas/OnlyFansDiscoveryFilters'
    SimilarCreatorsTikTokRequest:
      type: object
      required:
        - filter_key
        - filter_value
        - paging
      properties:
        platform:
          type: string
          enum:
            - tiktok
        filter_key:
          type: string
          enum:
            - url
            - username
            - id
        filter_value:
          type: string
          description: Email, platform url or profile handle
        paging:
          $ref: '#/components/schemas/PagingRequest'
        filters:
          $ref: '#/components/schemas/TikTokDiscoveryFilters'
    SimilarCreatorsTwitchRequest:
      type: object
      required:
        - filter_key
        - filter_value
        - paging
      properties:
        platform:
          type: string
          enum:
            - twitch
        filter_key:
          type: string
          enum:
            - url
            - username
            - id
        filter_value:
          type: string
          description: Email, platform url or profile handle
        paging:
          $ref: '#/components/schemas/PagingRequest'
        filters:
          $ref: '#/components/schemas/TwitchDiscoveryFilters'
    SimilarCreatorsTwitterRequest:
      type: object
      required:
        - filter_key
        - filter_value
        - paging
      properties:
        platform:
          type: string
          enum:
            - twitter
        filter_key:
          type: string
          enum:
            - url
            - username
            - id
        filter_value:
          type: string
          description: Email, platform url or profile handle
        paging:
          $ref: '#/components/schemas/PagingRequest'
        filters:
          $ref: '#/components/schemas/TwitterDiscoveryFilters'
    SimilarCreatorsYouTubeRequest:
      type: object
      required:
        - filter_key
        - filter_value
        - paging
      properties:
        platform:
          type: string
          enum:
            - youtube
        filter_key:
          type: string
          enum:
            - url
            - username
            - id
        filter_value:
          type: string
          description: Email, platform url or profile handle
        paging:
          $ref: '#/components/schemas/PagingRequest'
        filters:
          $ref: '#/components/schemas/YouTubeDiscoveryFilters'
    Sort:
      type: object
      properties:
        sort_by:
          type: string
          enum:
            - relevancy
            - engagement_rate
            - number_of_followers
            - growth_rate
          default: relevancy
        sort_order:
          type: string
          enum:
            - asc
            - desc
          default: desc
    SortRequest:
      type: object
      properties:
        sort_by:
          type: string
          enum:
            - relevancy
            - engagement_rate
            - number_of_followers
            - growth_rate
          default: relevancy
        sort_order:
          type: string
          enum:
            - asc
            - desc
          default: desc
    SourceList:
      type: object
      properties:
        id:
          type: integer
          description: Discovery list ID.
        name:
          type: string
          description: Discovery list name.
      required:
        - id
        - name
    SponsoredPostEngagementResponse:
      type: object
      properties:
        likes:
          type: integer
          description: Number of likes on the post.
          nullable: true
        comments:
          type: integer
          description: Number of comments on the post.
          nullable: true
    SponsoredPostResponse:
      type: object
      properties:
        post_id:
          type: string
          description: Platform-specific post identifier.
          nullable: true
        created_at:
          type: string
          description: Timestamp the post was created, in ISO 8601 format.
          nullable: true
        post_url:
          type: string
          description: URL to the post.
          nullable: true
        media_type:
          type: string
          description: Type of media in the post, e.g. photo, video, carousel.
          nullable: true
        thumbnail:
          type: string
          description: URL to the post's thumbnail image.
          nullable: true
        caption:
          type: string
          description: Text caption of the post.
          nullable: true
        mentions:
          type: array
          items:
            type: string
          description: Handles mentioned in the post.
        hashtags:
          type: array
          items:
            type: string
          description: Hashtags used in the post.
        engagement:
          $ref: '#/components/schemas/SponsoredPostEngagementResponse'
          description: Engagement metrics for the post.
    SubscriptionCreator:
      type: object
      properties:
        name:
          type: string
          description: The creator's handle on the platform.
        platform:
          type: string
          description: The creator's social media platform.
        avatar:
          type: string
          description: Signed URL of the creator's profile picture, or null.
        followers:
          type: string
          description: Latest scraped follower count for the creator, or null.
        source_list:
          type: string
          description: Name of the discovery list the creator came from, or null.
        added_at:
          type: string
          format: date-time
          description: When the creator was added to the subscription.
      required:
        - name
        - platform
        - added_at
    SubscriptionCreatorListPage:
      type: object
      properties:
        count:
          type: integer
          description: Total number of creators matching the filter.
        next:
          type: string
          format: uri
          description: URL of the next page, or null on the last page.
          nullable: true
        previous:
          type: string
          format: uri
          description: URL of the previous page, or null on the first page.
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionCreator'
          description: Creators on the current page.
      required:
        - count
        - results
    SubscriptionDeliveries24h:
      type: object
      properties:
        total:
          type: integer
          description: Deliveries attempted in the last 24 hours.
        successful:
          type: integer
          description: Successful deliveries in the last 24 hours.
        failed:
          type: integer
          description: Failed deliveries in the last 24 hours.
      required:
        - total
        - successful
        - failed
    SubscriptionListResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of subscriptions matching the filter.
        next:
          type: string
          format: uri
          description: URL of the next page, or null on the last page.
          nullable: true
        previous:
          type: string
          format: uri
          description: URL of the previous page, or null on the first page.
          nullable: true
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
          description: Subscriptions on the current page.
        summary:
          $ref: '#/components/schemas/SubscriptionSummary'
          description: Aggregate counts across all subscriptions matching the filter.
      required:
        - count
        - results
        - summary
    SubscriptionResponse:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        subscription_type:
          type: string
        platform:
          type: string
          description: The creator's social media platform.
        event_type:
          type: string
        status:
          type: string
        paused_reason:
          type: string
        filters:
          type: object
          nullable: true
          additionalProperties: {}
        interval:
          type: string
          description: Polling interval for this subscription's event type.
        notify_endpoints:
          type: array
          items:
            $ref: '#/components/schemas/NotifyEndpoint'
          description: Endpoints the subscription's events are delivered to.
        source_lists:
          type: array
          items:
            $ref: '#/components/schemas/SourceList'
          description: Discovery lists feeding creators into the subscription.
        sample_creators:
          type: string
          description: Up to 3 creators (handle + avatar) attached to the subscription.
        creator_count:
          type: string
          description: Total number of creators attached to the subscription.
        delivery_health:
          type: string
          description: Delivery counters (total, successful, and failed deliveries).
        last_event_at:
          type: string
          description: Timestamp of the most recent event for this subscription.
        credits_spent:
          type: string
          format: decimal
          description: >-
            Lifetime listening credits attributed to this subscription, accrued
            daily as 0.3 × its active creators (gross per-subscription). May
            exceed the deduplicated amount actually charged to the billing scope
            when creators are shared across subscriptions.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - subscription_type
        - platform
        - event_type
        - status
        - notify_endpoints
        - source_lists
        - credits_spent
        - created_at
        - updated_at
    SubscriptionSummary:
      type: object
      properties:
        active_subscriptions:
          type: integer
          description: >-
            Number of subscriptions currently active (respects the 'type'
            filter).
        deliveries_24h:
          $ref: '#/components/schemas/SubscriptionDeliveries24h'
          description: Delivery counters over the last 24 hours.
        success_rate:
          type: number
          format: double
          description: >-
            All-time successful-delivery percentage, or null when there have
            been no deliveries.
          nullable: true
        avg_detection_latency_seconds:
          type: number
          format: double
          description: >-
            Average time from detection to successful delivery, in seconds, or
            null when unavailable.
          nullable: true
      required:
        - active_subscriptions
        - deliveries_24h
    TikTokDiscoveryFilters:
      type: object
      properties:
        location:
          type: array
          items:
            type: string
            nullable: true
        type:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        profile_language:
          type: array
          items:
            type: string
            nullable: true
        ai_search:
          type: string
          description: >-
            Finds creators matching a single niche (e.g., 'plant-based
            recipes'), 3-150 characters; only letters, numbers and # - / , . ! ?
            + are supported. For best results, use one niche at a time—long or
            multi-topic phrases return weaker matches.
          nullable: true
        keywords_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        exclude_keywords_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        last_post:
          type: string
          description: 'Allowed values: any, 90, 365'
          nullable: true
        number_of_followers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        video_count:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        engagement_percent:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_views:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_likes:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_comments:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_video_downloads:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        posting_frequency:
          type: number
          format: double
          nullable: true
        follower_growth:
          allOf:
            - $ref: '#/components/schemas/GrowthRequest'
          nullable: true
        has_tik_tok_shop:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        exclude_private_profile:
          type: boolean
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        creator_has:
          $ref: '#/components/schemas/CreatorHasRequest'
        promotes_affiliate_links:
          type: boolean
          nullable: true
        has_done_brand_deals:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        has_link_in_bio:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        does_live_streaming:
          type: boolean
          nullable: true
        has_merch:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        exclude_role_based_emails:
          type: boolean
          nullable: true
          default: false
        exclude_handles:
          type: array
          items:
            type: string
        exclude_list:
          type: array
          items:
            type: integer
          description: >-
            IDs of exclusion lists to apply. Create and manage these via the
            Exclusion lists endpoints, then pass their IDs here; only lists for
            this platform are applied.
        exclude_default_list:
          type: boolean
          description: >-
            When true, applies the team's default exclusion list for this
            platform.
          default: false
        exclude_all_lists:
          type: boolean
          description: >-
            When true, applies every exclusion list for this platform (the
            default list and all specific lists).
          default: false
    Token:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the API key token.
        name:
          type: string
          description: Human-readable label for the token.
        scopes:
          type: array
          items:
            type: string
          description: Scopes granted to the token.
        active:
          type: boolean
          description: Whether the token is currently active.
        expires_at:
          type: string
          format: date-time
          description: Expiration timestamp, or null if the token never expires.
          nullable: true
        token:
          type: string
          description: >-
            The API key value used as the Bearer credential. Returned in full on
            every read.
        created_at:
          type: string
          format: date-time
          description: When the token was created.
        last_used_at:
          type: string
          format: date-time
          description: >-
            When the token was last used to authenticate a request, or null if
            never used.
          nullable: true
      required:
        - id
        - name
        - scopes
        - active
        - created_at
    TokenCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: >-
            Human-readable label for the token, shown in the token list. May be
            blank.
        scopes:
          type: array
          items:
            type: string
          description: >-
            Scopes to grant the token. Available value: `all`. Defaults to `all`
            if omitted.
    TokenRequest:
      type: object
      properties:
        grant_type:
          type: string
          enum:
            - authorization_code
            - refresh_token
          description: >-
            The grant type. Use authorization_code for desktop/CLI apps
            (requires PKCE), or refresh_token to refresh an expired access
            token.
        code:
          type: string
          description: >-
            The authorization code received in the redirect. Required for
            `authorization_code` grant.
        code_verifier:
          type: string
          description: >-
            PKCE code verifier. The random string used to generate the
            code_challenge. Required for `authorization_code` grant.
        client_id:
          type: string
          description: >-
            The client_id returned during client registration. Required for both
            grant types.
        redirect_uri:
          type: string
          description: >-
            Must match the redirect_uri used in the authorization request.
            Required for `authorization_code` grant.
        refresh_token:
          type: string
          description: >-
            The refresh token from a previous token response. Required for
            `refresh_token` grant.
        resource:
          type: string
          description: >-
            RFC 8707 resource indicator. If sent, must match the resource from
            the authorization request.
      required:
        - grant_type
        - client_id
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Bearer token for authenticating API requests.
        refresh_token:
          type: string
          description: >-
            Token used to obtain a new access token when the current one
            expires.
        token_type:
          type: string
          description: Always `Bearer`.
        expires_in:
          type: integer
          description: Lifetime of the access token in seconds.
        scope:
          type: string
          description: Space-separated list of scopes granted to this token.
      required:
        - access_token
        - refresh_token
        - token_type
        - expires_in
        - scope
    TokenUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: Human-readable label for the token, shown in the token list.
        active:
          type: boolean
          description: Set to `false` to deactivate the token, or `true` to reactivate it.
        expires_at:
          type: string
          format: date-time
          description: >-
            Expiration timestamp (ISO 8601). Pass `null` to remove the
            expiration and make the token non-expiring.
          nullable: true
        scopes:
          type: array
          items:
            type: string
          description: 'Replacement list of scopes for the token. Available value: `all`.'
    TwitchDiscoveryFilters:
      type: object
      properties:
        location:
          type: array
          items:
            type: string
            nullable: true
        gender:
          type: string
          nullable: true
        profile_language:
          type: array
          items:
            type: string
            nullable: true
        ai_search:
          type: string
          description: >-
            Finds creators matching a single niche (e.g., 'plant-based
            recipes'), 3-150 characters; only letters, numbers and # - / , . ! ?
            + are supported. For best results, use one niche at a time—long or
            multi-topic phrases return weaker matches.
          nullable: true
        games_played:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        is_twitch_partner:
          type: boolean
          nullable: true
          default: false
        keywords_in_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        most_recent_stream_date:
          type: string
          description: 'Allowed values: any, 30, 60, 90'
          nullable: true
        followers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        avg_views_last_30_days:
          $ref: '#/components/schemas/RangeRequest'
        streamed_hours_last_30_days:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        streams_count_last_30_days:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        maximum_views_count:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        creator_has:
          $ref: '#/components/schemas/CreatorHasRequest'
        promotes_affiliate_links:
          type: boolean
          nullable: true
        has_done_brand_deals:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        has_link_in_bio:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        does_live_streaming:
          type: boolean
          nullable: true
        has_merch:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        exclude_role_based_emails:
          type: boolean
          nullable: true
          default: false
        exclude_handles:
          type: array
          items:
            type: string
        exclude_list:
          type: array
          items:
            type: integer
          description: >-
            IDs of exclusion lists to apply. Create and manage these via the
            Exclusion lists endpoints, then pass their IDs here; only lists for
            this platform are applied.
        exclude_default_list:
          type: boolean
          description: >-
            When true, applies the team's default exclusion list for this
            platform.
          default: false
        exclude_all_lists:
          type: boolean
          description: >-
            When true, applies every exclusion list for this platform (the
            default list and all specific lists).
          default: false
    TwitterDiscoveryFilters:
      type: object
      properties:
        location:
          type: array
          items:
            type: string
            nullable: true
        type:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        profile_language:
          type: array
          items:
            type: string
            nullable: true
        ai_search:
          type: string
          description: >-
            Finds creators matching a single niche (e.g., 'plant-based
            recipes'), 3-150 characters; only letters, numbers and # - / , . ! ?
            + are supported. For best results, use one niche at a time—long or
            multi-topic phrases return weaker matches.
          nullable: true
        keywords_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        exclude_keywords_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        number_of_followers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_link_in_bio:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_in_tweets:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_not_in_tweets:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        last_post:
          type: string
          description: 'Allowed values: any, 90, 365'
          nullable: true
        tweets_count:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        engagement_percent:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_likes:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        creator_has:
          $ref: '#/components/schemas/CreatorHasRequest'
        promotes_affiliate_links:
          type: boolean
          nullable: true
        has_done_brand_deals:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        has_link_in_bio:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        does_live_streaming:
          type: boolean
          nullable: true
        has_merch:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        exclude_role_based_emails:
          type: boolean
          nullable: true
          default: false
        exclude_handles:
          type: array
          items:
            type: string
        exclude_list:
          type: array
          items:
            type: integer
          description: >-
            IDs of exclusion lists to apply. Create and manage these via the
            Exclusion lists endpoints, then pass their IDs here; only lists for
            this platform are applied.
        exclude_default_list:
          type: boolean
          description: >-
            When true, applies the team's default exclusion list for this
            platform.
          default: false
        exclude_all_lists:
          type: boolean
          description: >-
            When true, applies every exclusion list for this platform (the
            default list and all specific lists).
          default: false
    UpdateCampaignInput:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - paused
          description: >-
            Set to 'paused' or 'active'. Not allowed on draft campaigns, which
            activate automatically on the start date.
        content_types:
          type: array
          items:
            type: string
          description: Replaces the post types counted as campaign content.
        tracking_keywords:
          type: array
          items:
            type: string
          description: >-
            Replaces the campaign's tracking keywords. Pass an empty list to
            clear them.
        budget:
          type: string
          format: decimal
          description: Optional campaign budget.
          nullable: true
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
    UpdateCampaignInputRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - paused
          description: >-
            Set to 'paused' or 'active'. Not allowed on draft campaigns, which
            activate automatically on the start date.
        content_types:
          type: array
          items:
            type: string
          description: Replaces the post types counted as campaign content.
        tracking_keywords:
          type: array
          items:
            type: string
          description: >-
            Replaces the campaign's tracking keywords. Pass an empty list to
            clear them.
        budget:
          type: string
          format: decimal
          description: Optional campaign budget.
          nullable: true
          pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
    UpdateSubscriptionInput:
      type: object
      properties:
        name:
          type: string
          description: New subscription name.
        status:
          type: string
          enum:
            - active
            - paused
          description: >-
            Set to 'paused' or 'active'. Draft and completed-campaign
            subscriptions cannot be activated manually.
        notify_endpoints:
          type: array
          items:
            $ref: '#/components/schemas/NotifyEndpointInput'
          description: >-
            Replaces the subscription's notify endpoints. At least one is
            required when provided.
        add_handles:
          type: array
          items:
            type: string
          description: Creator handles to add to the subscription.
        list_ids:
          type: array
          items:
            type: integer
          description: >-
            Discovery list IDs whose creators are added. Each list's platform
            must match the subscription's platform.
        remove_handles:
          type: array
          items:
            type: string
          description: Creator handles to remove from the subscription.
        filters:
          type: object
          description: >-
            Replacement filter object, validated against the subscription's
            event_type.
          additionalProperties: {}
    UpdateSubscriptionInputRequest:
      type: object
      properties:
        name:
          type: string
          description: New subscription name.
        status:
          type: string
          enum:
            - active
            - paused
          description: >-
            Set to 'paused' or 'active'. Draft and completed-campaign
            subscriptions cannot be activated manually.
        notify_endpoints:
          type: array
          items:
            $ref: '#/components/schemas/NotifyEndpointInput'
          description: >-
            Replaces the subscription's notify endpoints. At least one is
            required when provided.
        add_handles:
          type: array
          items:
            type: string
          description: Creator handles to add to the subscription.
        list_ids:
          type: array
          items:
            type: integer
          description: >-
            Discovery list IDs whose creators are added. Each list's platform
            must match the subscription's platform.
        remove_handles:
          type: array
          items:
            type: string
          description: Creator handles to remove from the subscription.
        filters:
          type: object
          description: >-
            Replacement filter object, validated against the subscription's
            event_type.
          additionalProperties: {}
    UserInfoModel:
      type: object
      properties:
        pk:
          type: string
        username:
          type: string
          description: The creator's username on the platform.
          nullable: true
        full_name:
          type: string
          nullable: true
        profile_pic_url:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
      required:
        - pk
    ValidateJWTToken:
      type: object
      properties:
        username:
          type: string
          description: The creator's username on the platform.
        profile_picture:
          type: string
          description: >-
            URL to the creator's profile picture. This URL is temporary and
            expires after 24 hours. To keep the image, download it to your own
            storage before it expires.
          nullable: true
        email:
          type: string
          format: email
          description: The creator's email address.
        credits_remaining:
          type: number
          format: double
          description: Number of enrichment credits currently available on the account.
      required:
        - username
        - email
        - credits_remaining
    YouTubeDiscoveryFilters:
      type: object
      properties:
        location:
          type: array
          items:
            type: string
            nullable: true
        type:
          type: string
          nullable: true
        gender:
          type: string
          nullable: true
        profile_language:
          type: array
          items:
            type: string
            nullable: true
        ai_search:
          type: string
          description: >-
            Finds creators matching a single niche (e.g., 'plant-based
            recipes'), 3-150 characters; only letters, numbers and # - / , . ! ?
            + are supported. For best results, use one niche at a time—long or
            multi-topic phrases return weaker matches.
          nullable: true
        keywords_in_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_not_in_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_in_video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_not_in_video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_in_video_titles:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        keywords_not_in_video_titles:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        not_hashtags:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        topics:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        links_from_video_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        links_from_description:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        number_of_subscribers:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        engagement_percent:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_views_on_long_videos:
          $ref: '#/components/schemas/RangeRequest'
        median_views_long:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_views_on_shorts:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        number_of_videos:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        posting_frequency:
          type: number
          format: double
          nullable: true
        subscriber_growth:
          allOf:
            - $ref: '#/components/schemas/GrowthRequest'
          nullable: true
        is_verified:
          type: boolean
          nullable: true
        last_upload_long_video:
          type: string
          description: 'Allowed values: any, 90, 365'
          nullable: true
        last_upload_short_video:
          type: string
          description: 'Allowed values: any, 90, 365'
          nullable: true
        has_shorts:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        shorts_percentage:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        has_community_posts:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        streams_live:
          type: boolean
          nullable: true
          default: false
        has_merch:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        has_podcast:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        has_courses:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        has_membership:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        has_live_videos:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
          default: false
        is_monetizing:
          type: boolean
          nullable: true
          default: false
        income:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        long_video_duration:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_stream_views:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        average_stream_duration:
          allOf:
            - $ref: '#/components/schemas/RangeRequest'
          nullable: true
        last_stream_upload:
          type: string
          description: 'Allowed values: any, 90, 180, 365'
          nullable: true
        brands:
          type: array
          items:
            type: string
            nullable: true
          nullable: true
        creator_has:
          $ref: '#/components/schemas/CreatorHasRequest'
        promotes_affiliate_links:
          type: boolean
          nullable: true
        has_done_brand_deals:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        has_link_in_bio:
          type: boolean
          description: >-
            Only true is meaningful. Sending false or null has no effect
            (equivalent to omitting the field).
          nullable: true
        does_live_streaming:
          type: boolean
          nullable: true
        exclude_role_based_emails:
          type: boolean
          nullable: true
          default: false
        exclude_handles:
          type: array
          items:
            type: string
        exclude_list:
          type: array
          items:
            type: integer
          description: >-
            IDs of exclusion lists to apply. Create and manage these via the
            Exclusion lists endpoints, then pass their IDs here; only lists for
            this platform are applied.
        exclude_default_list:
          type: boolean
          description: >-
            When true, applies the team's default exclusion list for this
            platform.
          default: false
        exclude_all_lists:
          type: boolean
          description: >-
            When true, applies every exclusion list for this platform (the
            default list and all specific lists).
          default: false
    YouTubeTopic:
      type: object
      properties:
        topic_details:
          type: string
        sub_topic_details:
          type: array
          items:
            type: string
      required:
        - topic_details
        - sub_topic_details
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
servers:
  - url: https://api-dashboard.influencers.club
    description: Production
tags:
  - name: Discovery API
  - name: Similar Creators
  - name: Audience Overlap
  - name: Exclusion lists
    description: >-
      Manage lists of creator handles to exclude from Discovery and Similar
      Creators results.


      **Default vs specific lists.** Every team gets one *default* list per
      platform (Instagram, TikTok, etc.). It is created automatically the first
      time you touch it, you address it by platform — e.g. `GET
      /exclusion-lists/default/instagram/` — and it cannot be deleted; think of
      it as your standing blocklist. You can also create *specific* lists when
      one list is not enough — e.g. "Q4 campaign blocklist", "competitor
      handles", "do-not-contact". Specific lists get an `id` and are managed via
      `/exclusion-lists/{list_id}/…`; you can rename or delete them.


      **Adding handles alone does not filter search.** To actually filter
      Discovery or Similar Creators, pass one of these in `filters`:


      - `exclude_list: [42, 57]` — apply those list IDs

      - `exclude_default_list: true` — apply the platform's default list

      - `exclude_all_lists: true` — apply every list for that platform


      **Example flow**


      1. `POST /exclusion-lists/` with `{ "name": "Competitors", "platform":
      "instagram" }` → returns `id: 42`

      2. `POST /exclusion-lists/42/entries/` with `{ "handles": ["brand_x",
      "brand_y"] }`

      3. `POST /discovery/` with `filters.exclude_list: [42]` — `brand_x` and
      `brand_y` are now filtered out.


      For the default list, skip step 1: `POST
      /exclusion-lists/default/instagram/entries/`, then search with
      `filters.exclude_default_list: true`.
  - name: Dictionary
    description: >
      Provides the complete set of supported filter values used by the Discovery
      and Similar Creators endpoints.


      These endpoints return all valid, platform-specific values (such as
      languages, locations, brands, YouTube topics, Twitch games, audience brand
      categories, audience brand names, audience interests, and audience
      locations) that can be used when constructing discovery queries.


      Clients should retrieve dictionary values programmatically to ensure only
      supported values are sent in requests. Available values may vary by
      platform and can evolve over time.
  - name: Connected Socials
  - name: Enrich by handle full
  - name: Enrich by handle profile
  - name: Enrich by handle analytics
  - name: Enrich by handle raw
  - name: Enrich by email
  - name: Batch enrichment
    description: 'Bulk enrichment jobs: create, check status, resume, and download results.'
  - name: Creator Posts
  - name: Post Details
  - name: Subscriptions
    description: >-
      Create and manage social-listening subscriptions — the monitoring configs
      that watch a set of creators (by handle or discovery list) and deliver
      matching activity to your notify endpoints (e.g. a webhook URL). Covers
      listing, retrieving, updating and deleting subscriptions, and managing
      their creators, details and exports.
  - name: Campaigns
    description: >-
      Higher-level monitoring campaigns that provision and manage the backing
      per-platform webhook subscriptions for you, and expose aggregated delivery
      stats — for monitoring across platforms under a single construct.
  - name: Events
    description: >-
      Activity detected on monitored creators — events such as `new_post`,
      `bio_change` and `follower_threshold` — with the full payload and
      per-endpoint delivery history and status (pending / sending / sent /
      failed / retrying). List events or fetch a single event.
  - name: Usage
    description: >-
      Current social-listening limits and active subscription counts for the
      account's scope, so a client can see how much of its monitoring quota is
      in use.
  - name: Account credits & usage
    description: Account-level endpoints (credits, usage).
  - name: API Keys
    description: >-
      API keys are the Bearer credentials used to authenticate requests to the
      public API. They are the preferred method for machine-to-machine
      integrations — scripts, backend services, and direct server-to-server
      calls where no user interaction is needed.


      You can hold multiple active API keys simultaneously — useful for
      separating credentials across environments or applications. Each key can
      be revoked individually without affecting the others.


      Pass the key in the `Authorization` header as `Bearer <YOUR_API_KEY>`.
  - name: OAuth
    description: >-
      OAuth 2.0 Authorization Code flow with PKCE, the recommended approach for
      connecting apps and services that act on behalf of a user. Desktop and CLI
      applications use this flow to obtain a token tied to a specific user's
      account without ever handling their password.


      Call order:

      1. **Register** (`POST /oauth/register/`) — obtain a `client_id`
      (one-time, no auth required).

      2. **Authorize** (`GET /oauth/authorize/`) — open the browser to the
      consent URL. The user approves the consent screen in the dashboard.

      3. **Token** (`POST /oauth/token/`) — exchange the authorization code +
      PKCE verifier for an access token.


      The access token is used as a Bearer credential in the `Authorization`
      header, the same way as an API key.
x-tagGroups:
  - name: Creator Discovery
    tags:
      - Discovery API
      - Similar Creators
      - Audience Overlap
      - Exclusion lists
      - Dictionary
  - name: Creator Enrichment
    tags:
      - Connected Socials
      - Enrich by handle full
      - Enrich by handle profile
      - Enrich by handle analytics
      - Enrich by handle raw
      - Enrich by email
      - Batch enrichment
  - name: Creator Monitoring
    tags:
      - Subscriptions
      - Campaigns
      - Events
      - Usage
  - name: Creator Content
    tags:
      - Creator Posts
      - Post Details
  - name: Account & Authentication
    tags:
      - Account credits & usage
      - API Keys
      - OAuth
