> ## Documentation Index
> Fetch the complete documentation index at: https://growi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# List ad sources
> The content the dashboard ad builder offers: creator social posts (newest first), TikTok Shop videos that sold in the range (highest GMV first), or approved content submissions. Each row's creative_source goes into creative on POST /meta_ads/bulk.
Lists creator content you can turn into Meta ads: social posts (newest first), TikTok Shop videos that sold in the date range (highest GMV first), or approved content submissions.
Step 1 of the [Meta ads automation flow](/essentials/meta-ads-automation).
## Sources
| `source` | What it lists | Order | `creative_source` keys |
| - | - | - | - |
| `social_posts` (default) | Creator posts Growi tracks for your organization | Newest first | `social_post_id` |
| `tik_tok_shop_videos` | TikTok Shop videos that sold in your shop in the date range | Highest GMV first | `tts_external_id`, `tts_username` |
| `submissions` | Approved video and image content submissions | Newest first | `content_submission_version_id` |
Pass `ad_attachment=not_attached` to skip content that already backs an ad. That is the usual filter for a daily job. Dates default to the last 30 days, and a range can be up to 366 days.
## Fields to carry into the ad
* `creative_source`: copy its keys into `creative` on [Create ads in bulk](/api-reference/endpoint/meta-ads/bulk-create-ads).
* `meta_partnership_ad_request_id`: when set, send it to run the ad as the creator (a partnership ad).
* `whitelisting_status`: `whitelisted` means every Instagram account of the creator approved partnership ads; `partial`, `not_whitelisted` and `no_instagram` mean some, none, or no Instagram account.
* `creator.id`: pass it as `creator_ids` to [Get builder options](/api-reference/endpoint/meta-ads/get-builder-options) for the creator's tracking link.
* `campaign_affiliate_id`: the creator enrollment the content is attributed to, when known.
Filters are checked against your organization. A `campaign_id`, `campaign_affiliate_id` or `creator_id` from another organization returns `422`, and so does `source=tik_tok_shop_videos` when no TikTok Shop is connected.
## Authentication
Any organization API key works, including view-only keys. A key acts as the person who created it, so that person needs the owner, admin or viewer role. See [Rate limits and authentication](/api-reference/introduction).
## Errors
| Status | When |
| - | - |
| `401` | Missing or invalid API key, or the person who created the key is no longer an owner, admin or viewer of the organization |
| `404` | organization\_id is not a child brand of the key's organization |
| `422` | Invalid filter, a filter that points at another organization, or no TikTok Shop connected |
| `429` | Rate limited: 2 seconds between requests, and 40 requests per hour per key by default |
```bash cURL theme={"dark"}
curl -X GET "https://api.growi.io/api/public/v1/meta_ads/sources?source=social_posts&ad_attachment=not_attached&start_date=2026-10-01&end_date=2026-10-14" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```json 200 theme={"dark"}
{
"success": true,
"source": "social_posts",
"data": [
{
"source": "social_post",
"id": "instagram:3456789012345678901",
"creative_source": {
"social_post_id": "instagram:3456789012345678901"
},
"platform": "instagram",
"creator": {
"id": 2628998,
"name": "Ava Creator",
"handle": "ava.creates"
},
"campaign_id": 123,
"campaign_affiliate_id": 3490313,
"thumbnail_url": "https://cdn.growi.io/posts/3456789012345678901.mp4",
"video_url": "https://cdn.growi.io/posts/3456789012345678901.mp4",
"share_url": "https://www.instagram.com/reel/DAbCdEf/",
"posted_at": "Oct 10, 2026",
"product": {
"id": 88,
"name": "Glow Serum"
},
"gmv": null,
"existing_meta_ad": null,
"meta_ad_code": {
"code": "AbCdEf123",
"status": "active"
},
"whitelisting_status": "whitelisted",
"meta_partnership_ad_request_id": 4410
}
],
"meta": {
"page": 1,
"per_page": 25,
"total_count": 1,
"total_pages": 1,
"has_more": false,
"returned": 1
}
}
```
```json 422 theme={"dark"}
{
"success": false,
"error": "campaign_id not found for this organization"
}
```
## OpenAPI
````yaml GET /meta_ads/sources
openapi: 3.0.1
info:
title: Growi API
description: >-
API documentation for Growi platform, showcasing the public tracking event
endpoint
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.growi.io/api/public/v1
security:
- bearerAuth: []
paths:
/meta_ads/sources:
get:
summary: Lists content that can become a Meta ad
description: >-
The content the dashboard ad builder offers: creator social posts
(newest first), TikTok Shop videos that sold in the range (highest GMV
first), or approved content submissions. Each row's creative_source goes
into creative on POST /meta_ads/bulk.
parameters:
- name: organization_id
in: query
required: false
schema:
type: integer
description: >-
Act on a child brand of the API key's organization. Omit it to act
on the key's own organization. Any other id returns 404.
- name: source
in: query
required: false
schema:
type: string
enum:
- social_posts
- tik_tok_shop_videos
- submissions
default: social_posts
description: Which content to list.
example: social_posts
- name: campaign_id
in: query
required: false
schema:
type: integer
description: >-
Only content attributed to this Growi campaign. Must belong to your
organization.
example: 123
- name: campaign_affiliate_id
in: query
required: false
schema:
type: integer
description: Only content from this enrollment. Must belong to your organization.
- name: creator_id
in: query
required: false
schema:
type: integer
description: Growi user id of a creator in your organization.
- name: platform
in: query
required: false
schema:
type: string
enum:
- instagram
- tik_tok
- youtube
- twitter
- facebook
description: social_posts only.
- name: ad_attachment
in: query
required: false
schema:
type: string
enum:
- all
- attached
- not_attached
default: all
description: >-
attached: content that already backs an ad. not_attached: content
without an ad yet.
example: not_attached
- name: start_date
in: query
required: false
schema:
type: string
description: >-
YYYY-MM-DD. Defaults to 30 days before end_date. For submissions the
date filter only applies when you send it.
example: '2026-10-01'
- name: end_date
in: query
required: false
schema:
type: string
description: YYYY-MM-DD. Defaults to today. The range can be at most 366 days.
example: '2026-10-12'
- name: search
in: query
required: false
schema:
type: string
description: Free-text search
- name: page
in: query
required: false
schema:
type: integer
default: 1
minimum: 1
description: Page number
- name: per_page
in: query
required: false
schema:
type: integer
default: 25
minimum: 1
maximum: 100
description: Rows per page
responses:
'200':
description: Content you can build ads from
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Always true on 200
source:
type: string
description: The source you asked for
data:
type: array
items:
type: object
properties:
source:
type: string
description: >-
social_post, tik_tok_shop_video or
content_submission_version
id:
type: string
description: >-
Row id. Social posts look like `instagram:`,
TikTok Shop videos `tts:`
creative_source:
type: object
properties:
social_post_id:
type: string
description: >-
Copy these keys into creative on POST
/meta_ads/bulk. One of social_post_id,
tts_external_id + tts_username, or
content_submission_version_id.
platform:
type: string
creator:
type: object
properties:
id:
type: integer
description: Growi user id of the creator
name:
type: string
handle:
type: string
campaign_id:
type: integer
campaign_affiliate_id:
type: integer
description: >-
The creator's enrollment the post is attributed to,
when known
thumbnail_url:
type: string
video_url:
type: string
share_url:
type: string
posted_at:
type: string
product:
type: object
properties:
id:
type: integer
name:
type: string
gmv:
nullable: true
existing_meta_ad:
nullable: true
description: The ad already built from this content, if any
meta_ad_code:
type: object
properties:
code:
type: string
status:
type: string
description: >-
Instagram ad code the creator shared for this post
(social posts only)
whitelisting_status:
type: string
description: >-
Partnership ads readiness: whitelisted, partial,
not_whitelisted, no_instagram, or null
meta_partnership_ad_request_id:
type: integer
description: >-
An approved partnership request. Pass it to run the
ad as the creator.
meta:
type: object
properties:
page:
type: integer
per_page:
type: integer
total_count:
type: integer
total_pages:
type: integer
has_more:
type: boolean
description: true when there is another page
returned:
type: integer
description: Rows in this page
example:
success: true
source: social_posts
data:
- source: social_post
id: instagram:3456789012345678901
creative_source:
social_post_id: instagram:3456789012345678901
platform: instagram
creator:
id: 2628998
name: Ava Creator
handle: ava.creates
campaign_id: 123
campaign_affiliate_id: 3490313
thumbnail_url: https://cdn.growi.io/posts/3456789012345678901.mp4
video_url: https://cdn.growi.io/posts/3456789012345678901.mp4
share_url: https://www.instagram.com/reel/DAbCdEf/
posted_at: Oct 10, 2026
product:
id: 88
name: Glow Serum
gmv: null
existing_meta_ad: null
meta_ad_code:
code: AbCdEf123
status: active
whitelisting_status: whitelisted
meta_partnership_ad_request_id: 4410
meta:
page: 1
per_page: 25
total_count: 1
total_pages: 1
has_more: false
returned: 1
'401':
description: >-
Missing or invalid API key, or the person who created the key is no
longer an owner, admin or viewer of the organization
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
examples:
missing_key:
summary: Missing or invalid key
value:
error: Not Authenticated
creator_left:
summary: Key creator no longer in the organization
value:
success: false
error: >-
The user who created this API key no longer has access to
this organization.
'404':
description: organization_id is not a child brand of the key's organization
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: Organization not found
'422':
description: >-
Unknown source or filter value, a filter id from another
organization, or no TikTok Shop connected
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: campaign_id not found for this organization
'429':
description: >-
Rate limited: 2 seconds between requests, and 40 requests per hour
per key by default
content:
application/json:
schema:
type: object
properties:
error:
type: string
retry_after:
type: integer
reset_time:
type: string
examples:
burst:
summary: Under 2 seconds since the last request
value:
error: >-
Rate limit exceeded. Please wait 2 seconds between
requests.
retry_after: 2
hourly:
summary: Hourly cap reached
value:
error: Hourly rate limit of 40 requests exceeded.
retry_after: 1520
reset_time: '2026-10-12T15:00:00Z'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.