OpenAPI

Meta ad search

Filter and paginate ad creatives. Estimates and budget tiers are not actual spend. Meta uses the service default date range when dates are omitted.

POST/v1/ads/meta/search

Authentication: X-API-Key
Required scope: ads:meta:search
Billing: Pricing follows your active account rules
Rate limits: View your active rate limits

Parameters

Send this request as a JSON body.

pageintegerOptional

Default: 1

1 ≤ page ≤ 1000

sizeintegerOptional

Default: 20

1 ≤ size ≤ 100

about_textstringOptional

关于文本模糊查询

material_typestringOptional

素材类型, 逗号分隔

cta_typestringOptional

cta类型, 逗号分隔

page_category_type_enstringOptional

页面类目, 逗号分隔

platform_categorystringOptional

页面类目, 逗号分隔

countrystringOptional

国家代码, 逗号分隔

publisher_platform_arrstringOptional

发布平台, 逗号分隔 (数组字段筛选)

creation_time_beginstringOptional

开始日期范围-起始 (YYYY-MM-DD)

creation_time_endstringOptional

开始日期范围-结束 (YYYY-MM-DD)

placement_days_gteintegerOptional

投放天数-起始

placement_days_lteintegerOptional

投放天数-结束

likes_gteintegerOptional

粉丝数-起始

likes_lteintegerOptional

粉丝数-结束

total_reach_gteintegerOptional

触达次数-起始

total_reach_lteintegerOptional

触达次数-结束

estimate_spend_gtenumberOptional

预估消耗-起始

estimate_spend_ltenumberOptional

预估消耗-结束

ad_creative_labelstringOptional

素材标签, 逗号分隔 (Exhausted,One-Hit,Others,Scaling)

is_political_pagebooleanOptional

是否政治页面

is_activebooleanOptional

是否投放中

is_eubooleanOptional

是否面向欧盟

sort_bystringOptional

排序字段；关键词检索未指定时默认按相关度

relevance · start_date · likes · placement_days · total_reach · estimate_spend

sort_orderstringOptional

Default: "DESC"

ASC · DESC

Response

successbooleanRequired

dataarrayOptional

Show fields

ad_archive_idstringRequired

page_idintegerOptional

titlestringOptional

about_textstringOptional

material_typestringOptional

obs_image_urlstringOptional

obs_video_hd_urlstringOptional

landing_page_urlstringOptional

active_statusbooleanOptional

start_datestringOptional

placement_daysintegerOptional

total_reachintegerOptional

estimate_spendnumberOptional

估算值，非实际账单

currencystringOptional

publisher_platformarrayOptional

Show fields

Schema details are unavailable for this endpoint.

errorobjectOptional

错误详情

Show fields

codeintegerRequired

业务错误码

messagestringRequired

可读错误信息

metaobjectOptional

响应元数据

Show fields

request_idstringOptional

请求唯一标识

Default: ""

pageintegerOptional

当前页码

sizeintegerOptional

每页数量

totalintegerOptional

总数

quota_remainingintegerOptional

剩余配额（-1 表示不限制）

Default: -1

service_levelstringOptional

本次请求的服务等级

langstringOptional

响应语言（cn/en），为空表示未翻译

platformstringOptional

本次请求的达人平台

recall_typestringOptional

召回类型：hybrid / vector / scalar

credits_consumedintegerOptional

本次请求扣减的积分数

Default: 0

credits_remainingintegerOptional

积分余额（-1 不限制）

Default: -1

billable_unitsintegerOptional

Server-calculated billable units for this response

Default: 0

0 ≤ billable_units ≤ ∞

skill_namestringOptional

调用方 skill 名称

skill_current_versionstringOptional

调用方 skill 当前版本

skill_latest_versionstringOptional

服务端声明的最新 skill 版本

skill_min_supported_versionstringOptional

服务端声明的最低支持版本

skill_update_availablebooleanOptional

是否存在可用 skill 更新

Default: false

skill_update_requiredbooleanOptional

是否要求更新 skill 后再继续使用

Default: false

skill_update_messagestringOptional

skill 更新提示文案

skill_update_manifest_urlstringOptional

skill 更新 manifest URL

Request example

curl -X POST 'http://api.creativault.vip/openapi/v1/ads/meta/search' \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $CV_API_KEY" \
  --data '{
  "page": 1,
  "size": 5,
  "country": "US"
}'

This example shows a representative API response.

Response example

{
  "success": true,
  "data": [
    {
      "ad_archive_id": "demo_ad_001",
      "page_id": 123,
      "title": "Example creative",
      "material_type": "video"
    }
  ],
  "error": null,
  "meta": {
    "request_id": "example_request",
    "quota_remaining": -1,
    "page": 1,
    "size": 5,
    "total": 1
  }
}

View error handling →