DeveloperDocs.api

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

DeveloperDocs.authentication: X-API-Key
DeveloperDocs.permission: ads:meta:search
DeveloperDocs.billing: DeveloperDocs.configuredBilling
DeveloperDocs.limits: DeveloperDocs.configuredLimits

DeveloperDocs.parameters

DeveloperDocs.jsonBody

pageintegerDeveloperDocs.optional

DeveloperDocs.defaultValue: 1

1 ≤ page ≤ 1000

sizeintegerDeveloperDocs.optional

DeveloperDocs.defaultValue: 20

1 ≤ size ≤ 100

about_textstringDeveloperDocs.optional

关于文本模糊查询

material_typestringDeveloperDocs.optional

素材类型, 逗号分隔

cta_typestringDeveloperDocs.optional

cta类型, 逗号分隔

page_category_type_enstringDeveloperDocs.optional

页面类目, 逗号分隔

platform_categorystringDeveloperDocs.optional

页面类目, 逗号分隔

countrystringDeveloperDocs.optional

国家代码, 逗号分隔

publisher_platform_arrstringDeveloperDocs.optional

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

creation_time_beginstringDeveloperDocs.optional

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

creation_time_endstringDeveloperDocs.optional

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

placement_days_gteintegerDeveloperDocs.optional

投放天数-起始

placement_days_lteintegerDeveloperDocs.optional

投放天数-结束

likes_gteintegerDeveloperDocs.optional

粉丝数-起始

likes_lteintegerDeveloperDocs.optional

粉丝数-结束

total_reach_gteintegerDeveloperDocs.optional

触达次数-起始

total_reach_lteintegerDeveloperDocs.optional

触达次数-结束

estimate_spend_gtenumberDeveloperDocs.optional

预估消耗-起始

estimate_spend_ltenumberDeveloperDocs.optional

预估消耗-结束

ad_creative_labelstringDeveloperDocs.optional

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

is_political_pagebooleanDeveloperDocs.optional

是否政治页面

is_activebooleanDeveloperDocs.optional

是否投放中

is_eubooleanDeveloperDocs.optional

是否面向欧盟

sort_bystringDeveloperDocs.optional

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

relevance · start_date · likes · placement_days · total_reach · estimate_spend

sort_orderstringDeveloperDocs.optional

DeveloperDocs.defaultValue: "DESC"

ASC · DESC

DeveloperDocs.response

successbooleanDeveloperDocs.required

dataarrayDeveloperDocs.optional

DeveloperDocs.showFields

ad_archive_idstringDeveloperDocs.required

page_idintegerDeveloperDocs.optional

titlestringDeveloperDocs.optional

about_textstringDeveloperDocs.optional

material_typestringDeveloperDocs.optional

obs_image_urlstringDeveloperDocs.optional

obs_video_hd_urlstringDeveloperDocs.optional

landing_page_urlstringDeveloperDocs.optional

active_statusbooleanDeveloperDocs.optional

start_datestringDeveloperDocs.optional

placement_daysintegerDeveloperDocs.optional

total_reachintegerDeveloperDocs.optional

estimate_spendnumberDeveloperDocs.optional

估算值，非实际账单

currencystringDeveloperDocs.optional

publisher_platformarrayDeveloperDocs.optional

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

errorobjectDeveloperDocs.optional

错误详情

DeveloperDocs.showFields

codeintegerDeveloperDocs.required

业务错误码

messagestringDeveloperDocs.required

可读错误信息

metaobjectDeveloperDocs.optional

响应元数据

DeveloperDocs.showFields

request_idstringDeveloperDocs.optional

请求唯一标识

DeveloperDocs.defaultValue: ""

pageintegerDeveloperDocs.optional

当前页码

sizeintegerDeveloperDocs.optional

每页数量

totalintegerDeveloperDocs.optional

总数

quota_remainingintegerDeveloperDocs.optional

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

DeveloperDocs.defaultValue: -1

service_levelstringDeveloperDocs.optional

本次请求的服务等级

langstringDeveloperDocs.optional

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

platformstringDeveloperDocs.optional

本次请求的达人平台

recall_typestringDeveloperDocs.optional

召回类型：hybrid / vector / scalar

credits_consumedintegerDeveloperDocs.optional

本次请求扣减的积分数

DeveloperDocs.defaultValue: 0

credits_remainingintegerDeveloperDocs.optional

积分余额（-1 不限制）

DeveloperDocs.defaultValue: -1

billable_unitsintegerDeveloperDocs.optional

Server-calculated billable units for this response

DeveloperDocs.defaultValue: 0

0 ≤ billable_units ≤ ∞

skill_namestringDeveloperDocs.optional

调用方 skill 名称

skill_current_versionstringDeveloperDocs.optional

调用方 skill 当前版本

skill_latest_versionstringDeveloperDocs.optional

服务端声明的最新 skill 版本

skill_min_supported_versionstringDeveloperDocs.optional

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

skill_update_availablebooleanDeveloperDocs.optional

是否存在可用 skill 更新

DeveloperDocs.defaultValue: false

skill_update_requiredbooleanDeveloperDocs.optional

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

DeveloperDocs.defaultValue: false

skill_update_messagestringDeveloperDocs.optional

skill 更新提示文案

skill_update_manifest_urlstringDeveloperDocs.optional

skill 更新 manifest URL

DeveloperDocs.requestExample

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

DeveloperDocs.exampleNotice

DeveloperDocs.responseExample

{
  "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
  }
}

DeveloperDocs.errorHelp →