---
title: "Get a creator outreach batch"
method: GET
path: "/api/v2/creator-search/outreach-batches/{id}"
tags: ["Creator"]
---

# Get a creator outreach batch

`GET /api/v2/creator-search/outreach-batches/{id}`

## Request

- Base URL: `https://api.instantly.ai`
- URL: `https://api.instantly.ai/api/v2/creator-search/outreach-batches/{id}`
- Auth: HTTP bearer

The creator list and its last conversion; `status` is `queued` or `running` until it ends.


Requires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`

## Path parameters

- `id` string, required

## Response `200`

Default Response

- object
  - `id` string, uuid, required: The creator list; also the id of its lead list
  - `list_id` string, uuid
  - `agent_id` string, uuid
  - `status` 'preparing' | 'queued' | 'running' | 'ready' | 'attaching' | 'attached' | 'partial' | 'failed', required: `queued` and `running` mean a conversion is still in progress
  - `platform` 'instagram' | 'tiktok' | 'youtube' | 'all', required
  - `search_kind` 'structured' | 'ai_text' | 'lookalike' | 'result_image' | 'image_upload', required
  - `query` string
  - `filters` object, required
    - `creator` string
    - `locations` union[]
      - union
        - string
        - number
    - `languages` string[]
    - `followers` object
      - `min` number
      - `max` number
    - `engagement_rate` object
      - `min` number
      - `max` number
    - `average_views` object
      - `min` number
      - `max` number
    - `growth_rate` object
      - `min` number
      - `max` number
    - `posting_frequency` object
      - `min` number
      - `max` number
    - `last_posted_days` number
    - `interests` union[]
      - union
        - string
        - number
    - `hashtags` string[]
    - `bio` string
    - `account_type` 'creator' | 'business' | 'regular'
    - `verified` boolean
    - `has_email` boolean
    - `authenticity_min` number
    - `brand_ids` union[]
      - union
        - string
        - number
    - `audience_locations` object[]
      - `id` union, required
        - string
        - number
      - `weight` number
    - `audience_languages` object[]
      - `id` union, required
        - string
        - number
      - `weight` number
    - `audience_interests` object[]
      - `id` union, required
        - string
        - number
      - `weight` number
  - `creators` object[], required
    - `creator_ref` string, required: Opaque reference to the creator in this workspace; pass it back to convert or find lookalikes. It expires after a while: search again for a fresh one.
    - `platform` 'instagram' | 'tiktok' | 'youtube', required
    - `name` string, required
    - `handle` string, required
    - `profile_url` string, nullable
    - `avatar_url` string, nullable
    - `bio` string, nullable
    - `location` string, nullable
    - `category` string, nullable
    - `followers` number, required
    - `engagement_rate` number, required: A fraction, 0 to 1
    - `average_views` number, nullable
    - `posting_frequency` number, nullable: Posts per month
    - `growth_rate` number, nullable
    - `has_email` boolean, required: Whether an email is known for this creator; converting one without an email charges nothing
    - `is_verified` boolean, nullable
    - `is_unlocked` boolean, required: Whether this workspace already bought the creator's insights
    - `collaboration_brands` string[], required
    - `content` object[], required: Recent posts
      - `id` string, required
      - `url` string
      - `thumbnail_url` string
      - `video_url` string
      - `media_type` 'image' | 'video' | 'carousel'
      - `visual_ref` string: Pass as `visual_ref` to find creators with similar posts
      - `caption` string
      - `hashtags` string[]
      - `published_at` string
      - `likes` number
      - `comments` number
      - `views` number
      - `shares` number
      - `is_sponsored` boolean
    - `list_member_id` string
    - `public_report` object
      - `audience` object
        - `geography` object[]
          - `label` string, required
          - `value` number, required
        - `ages` object[]
          - `label` string, required
          - `value` number, required
        - `genders` object[]
          - `label` string, required
          - `value` number, required
        - `languages` object[]
          - `label` string, required
          - `value` number, required
        - `interests` object[]
          - `label` string, required
          - `value` number, required
        - `credibility` number: Share of followers that look like real people, 0 to 1
      - `performance` object
        - `average_likes` number
        - `average_comments` number
        - `average_views` number
        - `engagement_rate` number
        - `posting_frequency` number: Posts per month
        - `follower_growth` number
        - `paid_post_performance` number
        - `content_type_performance` object[]
          - `label` string, required
          - `value` number, required
      - `recent_content` object[]
        - `id` string, required
        - `url` string
        - `thumbnail_url` string
        - `video_url` string
        - `media_type` 'image' | 'video' | 'carousel'
        - `visual_ref` string: Pass as `visual_ref` to find creators with similar posts
        - `caption` string
        - `hashtags` string[]
        - `published_at` string
        - `likes` number
        - `comments` number
        - `views` number
        - `shares` number
        - `is_sponsored` boolean
      - `popular_content` object[]
        - `id` string, required
        - `url` string
        - `thumbnail_url` string
        - `video_url` string
        - `media_type` 'image' | 'video' | 'carousel'
        - `visual_ref` string: Pass as `visual_ref` to find creators with similar posts
        - `caption` string
        - `hashtags` string[]
        - `published_at` string
        - `likes` number
        - `comments` number
        - `views` number
        - `shares` number
        - `is_sponsored` boolean
      - `sponsored_content` object[]
        - `id` string, required
        - `url` string
        - `thumbnail_url` string
        - `video_url` string
        - `media_type` 'image' | 'video' | 'carousel'
        - `visual_ref` string: Pass as `visual_ref` to find creators with similar posts
        - `caption` string
        - `hashtags` string[]
        - `published_at` string
        - `likes` number
        - `comments` number
        - `views` number
        - `shares` number
        - `is_sponsored` boolean
      - `collaborations` object[]
        - `brand` string, required
        - `posts` number
        - `likes` number
        - `comments` number
        - `views` number
    - `collaborations` object[]
      - `brand` string, required
      - `posts` number
      - `likes` number
      - `comments` number
      - `views` number
    - `review` object
      - `decision` 'approved' | 'passed' | 'null', nullable
      - `decided_by` string, nullable
      - `comments` object[]
        - `id` string
        - `author_name` string
        - `body` string
        - `timestamp_created` string
    - `email` string: The email the conversion found
    - `lead_id` string, uuid: The lead created for this creator
  - `lead_ids` string[], required
  - `run` object, nullable: How the last conversion run went; null until one has run
    - `selected_count` integer
    - `email_ready_count` integer: Leads created with an email
    - `missing_email_count` integer: Creators without an email; not charged
    - `duplicate_email_count` integer: Emails already in the list; not added again
    - `credits_cost` number
    - `can_continue` boolean
    - `verifying_count` integer: Leads whose email is still being verified
    - `error_code` string, nullable
    - `pages_loaded` integer
    - `paging_credits` number
    - `campaign` object: Set when the run also adds its creators to `campaign_id`
      - `id` string, uuid, required
      - `status` 'pending' | 'added' | 'failed', required: `pending` until the emails are checked and the valid creators are added
      - `added_count` integer, required
      - `error_code` 'lead_limit_reached' | 'destination_unavailable' | 'null', nullable, required
  - `error_code` string, nullable

## Other responses

- `400`: The request is invalid (e.g. missing required fields, invalid field values, or an invalid state for the operation)
- `401`: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
- `402`: Default Response
- `403`: This request is forbidden (the API key scope or workspace plan does not allow this action)
- `404`: The requested resource was not found
- `429`: You have exceeded the rate limit. Please check the rate limit docs for more information.

## Changes

- **2026-11-03** `c781051105a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/instantly/apis/api-explorer/changes/api/v2/creator-search/outreach-batches/:id/get.md)

---

[API](https://skmtc.dev/instantly/apis/api-explorer.md) - [All operations](https://skmtc.dev/instantly/apis/api-explorer/llms.txt) - [OpenAPI document](https://skmtc.dev/instantly/apis/api-explorer/revisions/406ab2c4f714?raw)