Reading as an agent? These docs are available as
/docs/api.json
(LLM-focused) and as an OpenAPI spec.
Manage projects and reusable audiences from agents, internal tools, and automation. Every request is authenticated with a bearer token and returns JSON.
The examples below are ready to read with placeholder values. Sign in to generate a real key in one click and have it filled in automatically.
Set up Growth Chicken to generate ads for my product. Walk me through it, doing each step for me where you can and pausing only when you need something only I can provide.
Growth Chicken turns a product page into on-brand Still and Video ads through a REST API at https://trygrowthchicken.com. Run this setup interactively: ask me for one thing at a time and wait for my answer before moving on. Read the API reference at https://trygrowthchicken.com/docs/openapi.json for exact endpoints and request bodies.
1. Ask me for two things and wait for my answers: my email address, and my product URL (the page my ads should be based on).
2. Create my account for me: POST https://trygrowthchicken.com/api/v1/accounts with body {"email": "<my email>"}. This call needs no auth header. On success it emails me a confirmation link. (If it returns 429 you have hit the rate limit, or I may already have an account - tell me.) Then tell me to check my email and click the confirmation link, and wait until I confirm I have done it. Clicking the link signs me in.
3. Have me create an API key inside the app: tell me to open https://trygrowthchicken.com/docs/api while signed in and click "Create API key", then copy the key it shows once and paste it back to you. Wait for it.
4. Store the key safely, do not just leave it in our chat: write it to a gitignored secrets file (for example a .env that is listed in .gitignore, as GROWTH_CHICKEN_API_TOKEN=<my key>) or your tool's secret store. Never print it back to me, never commit it, and never paste it into code you show me. Send it on every API request as the header "Authorization: Bearer <my key>".
5. Once the key works, finish the rest in one go:
a. Create a project from my product page: POST https://trygrowthchicken.com/api/v1/projects/from_url with body {"url": "<my product URL>"}. This can take several seconds. Save the project "slug" from the response.
b. Check my balance and per-variant output prices with GET https://trygrowthchicken.com/api/v1/account, and discover styles with GET https://trygrowthchicken.com/api/v1/styles. Then generate exactly two sample ads. Generation is async: each create returns HTTP 202 with a "poll_url"; GET it until "status" is "ready". These spend from the starter token balance, so generate exactly these two and no more:
- Meme still: POST https://trygrowthchicken.com/api/v1/projects/<slug>/ads with {"ad": {"output": "image", "style_scope": "memes"}}
- Video: POST https://trygrowthchicken.com/api/v1/projects/<slug>/ads with {"ad": {"output": "video", "style_scope": "templates"}}
c. When each ad is "ready", each ad is generated at every size, so use any entry in "files" to download that size's PNG or MP4. The first raster request may return 202 while it renders, so retry until 200; "document_url" is the self-contained HTML fallback.
d. Show me both ads.
Send your key as a bearer token in the Authorization header. Requests without a valid key return 401.
Highlighted values like YOUR_PROJECT_SLUG are placeholders. Swap in your own.
Inspect the authenticated account and create API access for a confirmed user.
/accounts
Set up an account (sends a confirmation email)
{
"email": "[email protected]"
}
curl -X POST https://trygrowthchicken.com/api/v1/accounts \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]"}'
/account
Get account token balance
curl https://trygrowthchicken.com/api/v1/account \
-H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"account": {
"user_id": "00000000-0000-0000-0000-000000000301",
"email": "[email protected]",
"token_balance": 1234,
"output_options": [
{
"id": "image",
"label": "Still ad",
"description": "Create an editable still using any compatible ad layout or meme format.",
"token_cost": 25,
"cost_basis": "per_variant"
},
{
"id": "video",
"label": "Video ad",
"description": "Generate a moving scene using a compatible ad layout.",
"token_cost": 163,
"cost_basis": "per_variant"
}
]
}
}
Create and manage product briefs. Projects own audiences, assets, generated ads, and the distribution records below.
/projects
List projects
curl https://trygrowthchicken.com/api/v1/projects \
-H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"projects": [
{
"id": "00000000-0000-0000-0000-000000000001",
"slug": "launchpad",
"name": "LaunchPad",
"description": "A complete project brief.",
"tagline": "Launch creative faster.",
"visual_direction": "Bright product-led scenes with crisp UI moments and clean negative space.",
"avatar_url": "https://cdn.example.com/brand-mark.png",
"status": "active",
"source_url": "https://example.com",
"external_identifiers": {
"meta_ad_account": "act_1234567890",
"product_key": "launchpad"
},
"brand_kit": {
"colors": [
"#111111"
],
"font_preferences": {
"direction": "Clean sans."
},
"logos": [],
"style_notes": "Bright."
},
"created_at": "2026-05-25T12:00:00Z",
"updated_at": "2026-05-25T12:00:00Z",
"assets_count": 0,
"creatives_count": 0
}
]
}
/projects
Create project
{
"project": {
"name": "LaunchPad",
"description": "A detailed product brief with audience, offer, proof points, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.",
"tagline": "Launch creative faster.",
"visual_direction": "Bright product-led scenes with crisp UI moments, confident lighting, clean negative space, and occasional high-contrast accent shapes.",
"source_url": "https://example.com",
"ad_health_monitored": true,
"target_cpa": "24.50",
"target_cpa_currency": "USD",
"brand_kit": {
"colors": [
"#111111",
"#ffcc00"
],
"font_preferences": {
"direction": "Clean geometric sans with expressive display accents."
},
"style_notes": "Bright, direct, and product-led."
}
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects \
-H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"project":{"name":"LaunchPad","description":"A detailed product brief with audience, offer, proof points, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments, confident lighting, clean negative space, and occasional high-contrast accent shapes.","source_url":"https://example.com","ad_health_monitored":true,"target_cpa":"24.50","target_cpa_currency":"USD","brand_kit":{"colors":["#111111","#ffcc00"],"font_preferences":{"direction":"Clean geometric sans with expressive display accents."},"style_notes":"Bright, direct, and product-led."}}}'
{
"project": {
"id": "00000000-0000-0000-0000-000000000001",
"slug": "launchpad",
"name": "LaunchPad",
"description": "A complete project brief.",
"tagline": "Launch creative faster.",
"visual_direction": "Bright product-led scenes with crisp UI moments and clean negative space.",
"avatar_url": "https://cdn.example.com/brand-mark.png",
"status": "active",
"source_url": "https://example.com",
"external_identifiers": {
"meta_ad_account": "act_1234567890",
"product_key": "launchpad"
},
"brand_kit": {
"colors": [
"#111111"
],
"font_preferences": {
"direction": "Clean sans."
},
"logos": [],
"style_notes": "Bright."
},
"created_at": "2026-05-25T12:00:00Z",
"updated_at": "2026-05-25T12:00:00Z",
"assets_count": 0,
"creatives_count": 0
}
}
/projects/from_url
Create project from a URL
{
"url": "https://example.com"
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/from_url \
-H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
{
"project": {
"id": "00000000-0000-0000-0000-000000000001",
"slug": "launchpad",
"name": "LaunchPad",
"description": "A complete project brief.",
"tagline": "Launch creative faster.",
"visual_direction": "Bright product-led scenes with crisp UI moments and clean negative space.",
"avatar_url": "https://cdn.example.com/brand-mark.png",
"status": "active",
"source_url": "https://example.com",
"external_identifiers": {
"meta_ad_account": "act_1234567890",
"product_key": "launchpad"
},
"brand_kit": {
"colors": [
"#111111"
],
"font_preferences": {
"direction": "Clean sans."
},
"logos": [],
"style_notes": "Bright."
},
"created_at": "2026-05-25T12:00:00Z",
"updated_at": "2026-05-25T12:00:00Z",
"assets_count": 0,
"creatives_count": 0
}
}
/projects/{id}
Get project
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"project": {
"id": "00000000-0000-0000-0000-000000000001",
"slug": "launchpad",
"name": "LaunchPad",
"description": "A complete project brief.",
"tagline": "Launch creative faster.",
"visual_direction": "Bright product-led scenes with crisp UI moments and clean negative space.",
"avatar_url": "https://cdn.example.com/brand-mark.png",
"status": "active",
"source_url": "https://example.com",
"external_identifiers": {
"meta_ad_account": "act_1234567890",
"product_key": "launchpad"
},
"brand_kit": {
"colors": [
"#111111"
],
"font_preferences": {
"direction": "Clean sans."
},
"logos": [],
"style_notes": "Bright."
},
"created_at": "2026-05-25T12:00:00Z",
"updated_at": "2026-05-25T12:00:00Z",
"assets_count": 0,
"creatives_count": 0
}
}
/projects/{id}
Update project
{
"project": {
"name": "LaunchPad",
"description": "A detailed product brief with audience, offer, proof points, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.",
"tagline": "Launch creative faster.",
"visual_direction": "Bright product-led scenes with crisp UI moments, confident lighting, clean negative space, and occasional high-contrast accent shapes.",
"source_url": "https://example.com",
"ad_health_monitored": true,
"target_cpa": "24.50",
"target_cpa_currency": "USD",
"brand_kit": {
"colors": [
"#111111",
"#ffcc00"
],
"font_preferences": {
"direction": "Clean geometric sans with expressive display accents."
},
"style_notes": "Bright, direct, and product-led."
}
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"project":{"name":"LaunchPad","description":"A detailed product brief with audience, offer, proof points, tone, constraints, claims, channel context, product benefits, objections, conversion goal, and enough substance for generated creative work.","tagline":"Launch creative faster.","visual_direction":"Bright product-led scenes with crisp UI moments, confident lighting, clean negative space, and occasional high-contrast accent shapes.","source_url":"https://example.com","ad_health_monitored":true,"target_cpa":"24.50","target_cpa_currency":"USD","brand_kit":{"colors":["#111111","#ffcc00"],"font_preferences":{"direction":"Clean geometric sans with expressive display accents."},"style_notes":"Bright, direct, and product-led."}}}'
{
"project": {
"id": "00000000-0000-0000-0000-000000000001",
"slug": "launchpad",
"name": "LaunchPad",
"description": "A complete project brief.",
"tagline": "Launch creative faster.",
"visual_direction": "Bright product-led scenes with crisp UI moments and clean negative space.",
"avatar_url": "https://cdn.example.com/brand-mark.png",
"status": "active",
"source_url": "https://example.com",
"external_identifiers": {
"meta_ad_account": "act_1234567890",
"product_key": "launchpad"
},
"brand_kit": {
"colors": [
"#111111"
],
"font_preferences": {
"direction": "Clean sans."
},
"logos": [],
"style_notes": "Bright."
},
"created_at": "2026-05-25T12:00:00Z",
"updated_at": "2026-05-25T12:00:00Z",
"assets_count": 0,
"creatives_count": 0
}
}
/projects/{id}
Delete project
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Discover customer-selectable regular templates and meme formats, their supported outputs, and semantic roles.
/styles
List global ad styles
curl https://trygrowthchicken.com/api/v1/styles \
-H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"styles": [
{
"id": "meme:impossible-choice",
"category": "meme",
"name": "Impossible Choice",
"description": "Two competing options that make the hesitation instantly recognizable.",
"tags": [
"decision",
"dilemma",
"conflict"
],
"outputs": [
"image"
],
"template_key": "meme_panel",
"meme_base": "impossible-choice",
"editable_slots": [
{
"name": "option_left",
"role": "first_option",
"budget": 22,
"max_lines": 2,
"max_words": 4
},
{
"name": "option_right",
"role": "second_option",
"budget": 22,
"max_lines": 2,
"max_words": 4
}
],
"character_roles": [
{
"name": "decider",
"guidance": "The person, creature, product, or team forced to choose."
}
]
}
]
}
Reusable audience definitions and creative rules scoped to a project.
List audiences
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"audiences": [
{
"id": "00000000-0000-0000-0000-000000000101",
"slug": "finance_operators",
"project_id": "00000000-0000-0000-0000-000000000001",
"organization_id": "00000000-0000-0000-0000-000000000201",
"creator_user_id": "00000000-0000-0000-0000-000000000301",
"name": "Finance operators",
"description": "Operations and finance leaders who need audit-ready campaign workflows.",
"rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
"metadata": {
"segment": "finance"
},
"used_by_ads": false,
"created_at": "2026-06-18T12:00:00Z",
"updated_at": "2026-06-18T12:00:00Z"
}
]
}
Create audience
{
"audience": {
"name": "Finance operators",
"description": "Operations and finance leaders who need audit-ready campaign workflows.",
"rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
"metadata": {
"segment": "finance"
}
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"audience":{"name":"Finance operators","description":"Operations and finance leaders who need audit-ready campaign workflows.","rules":"Avoid hype. Mention controls, approvals, and reliable reporting.","metadata":{"segment":"finance"}}}'
{
"audience": {
"id": "00000000-0000-0000-0000-000000000101",
"slug": "finance_operators",
"project_id": "00000000-0000-0000-0000-000000000001",
"organization_id": "00000000-0000-0000-0000-000000000201",
"creator_user_id": "00000000-0000-0000-0000-000000000301",
"name": "Finance operators",
"description": "Operations and finance leaders who need audit-ready campaign workflows.",
"rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
"metadata": {
"segment": "finance"
},
"used_by_ads": false,
"created_at": "2026-06-18T12:00:00Z",
"updated_at": "2026-06-18T12:00:00Z"
}
}
Get audience
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"audience": {
"id": "00000000-0000-0000-0000-000000000101",
"slug": "finance_operators",
"project_id": "00000000-0000-0000-0000-000000000001",
"organization_id": "00000000-0000-0000-0000-000000000201",
"creator_user_id": "00000000-0000-0000-0000-000000000301",
"name": "Finance operators",
"description": "Operations and finance leaders who need audit-ready campaign workflows.",
"rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
"metadata": {
"segment": "finance"
},
"used_by_ads": false,
"created_at": "2026-06-18T12:00:00Z",
"updated_at": "2026-06-18T12:00:00Z"
}
}
Update audience
{
"audience": {
"name": "Finance operators",
"description": "Operations and finance leaders who need audit-ready campaign workflows.",
"rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
"metadata": {
"segment": "finance"
}
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"audience":{"name":"Finance operators","description":"Operations and finance leaders who need audit-ready campaign workflows.","rules":"Avoid hype. Mention controls, approvals, and reliable reporting.","metadata":{"segment":"finance"}}}'
{
"audience": {
"id": "00000000-0000-0000-0000-000000000101",
"slug": "finance_operators",
"project_id": "00000000-0000-0000-0000-000000000001",
"organization_id": "00000000-0000-0000-0000-000000000201",
"creator_user_id": "00000000-0000-0000-0000-000000000301",
"name": "Finance operators",
"description": "Operations and finance leaders who need audit-ready campaign workflows.",
"rules": "Avoid hype. Mention controls, approvals, and reliable reporting.",
"metadata": {
"segment": "finance"
},
"used_by_ads": false,
"created_at": "2026-06-18T12:00:00Z",
"updated_at": "2026-06-18T12:00:00Z"
}
}
Delete audience
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/audiences/YOUR_AUDIENCE_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Durable directional beliefs and the generation brief that summarizes current learning and ongoing attempts.
List hypotheses
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"hypotheses": [
{
"id": "00000000-0000-0000-0000-000000000801",
"project_id": "00000000-0000-0000-0000-000000000001",
"organization_id": "00000000-0000-0000-0000-000000000201",
"statement": "Founder-led voice improves cold-traffic recall",
"audience_id": "00000000-0000-0000-0000-000000000101",
"audience_label": "Finance operators",
"author": "agent:weekly-reviewer",
"agent_authored": true,
"created_at": "2026-07-20T09:00:00Z",
"updated_at": "2026-07-20T09:00:00Z"
}
]
}
Create hypothesis
{
"hypothesis": {
"statement": "Founder-led voice improves cold-traffic recall",
"audience_id": "00000000-0000-0000-0000-000000000101"
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"hypothesis":{"statement":"Founder-led voice improves cold-traffic recall","audience_id":"00000000-0000-0000-0000-000000000101"}}'
{
"hypothesis": {
"id": "00000000-0000-0000-0000-000000000801",
"project_id": "00000000-0000-0000-0000-000000000001",
"organization_id": "00000000-0000-0000-0000-000000000201",
"statement": "Founder-led voice improves cold-traffic recall",
"audience_id": "00000000-0000-0000-0000-000000000101",
"audience_label": "Finance operators",
"author": "agent:weekly-reviewer",
"agent_authored": true,
"created_at": "2026-07-20T09:00:00Z",
"updated_at": "2026-07-20T09:00:00Z"
}
}
Get the hypothesis brief for ad generation
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/brief \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"brief": {
"project_id": "00000000-0000-0000-0000-000000000001",
"scope": {
"audience_id": "00000000-0000-0000-0000-000000000101",
"audience": "Finance operators"
},
"hypotheses": [
{
"id": "00000000-0000-0000-0000-000000000801",
"statement": "Founder-led voice improves cold-traffic recall",
"audience_label": "Finance operators",
"findings_count": 2,
"signal_counts": {
"positive": 1,
"neutral": 1
},
"untested": false,
"contested": false,
"latest_signal": "positive",
"latest_finding_at": "2026-07-18T17:00:00Z",
"ongoing_experiments": [
{
"id": "00000000-0000-0000-0000-000000000901",
"context": "Founder narration with the offer in the first two seconds",
"window_start": "2026-07-20T09:00:00Z",
"window_end": null,
"subjects": [
{
"id": "00000000-0000-0000-0000-000000000a01",
"name": "Founder opening",
"kind": "internal",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"ad_run_id": null,
"external_ref": null
}
]
}
]
}
],
"precedent": [
{
"id": "00000000-0000-0000-0000-000000000802",
"statement": "Human narration improves product comprehension",
"audience_label": "all audiences"
}
]
}
}
Get hypothesis
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"hypothesis": {
"id": "00000000-0000-0000-0000-000000000801",
"project_id": "00000000-0000-0000-0000-000000000001",
"organization_id": "00000000-0000-0000-0000-000000000201",
"statement": "Founder-led voice improves cold-traffic recall",
"audience_id": "00000000-0000-0000-0000-000000000101",
"audience_label": "Finance operators",
"author": "agent:weekly-reviewer",
"agent_authored": true,
"created_at": "2026-07-20T09:00:00Z",
"updated_at": "2026-07-20T09:00:00Z"
}
}
Update hypothesis statement
{
"hypothesis": {
"statement": "Founder-led voice improves cold-traffic recall",
"audience_id": "00000000-0000-0000-0000-000000000101"
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"hypothesis":{"statement":"Founder-led voice improves cold-traffic recall","audience_id":"00000000-0000-0000-0000-000000000101"}}'
{
"hypothesis": {
"id": "00000000-0000-0000-0000-000000000801",
"project_id": "00000000-0000-0000-0000-000000000001",
"organization_id": "00000000-0000-0000-0000-000000000201",
"statement": "Founder-led voice improves cold-traffic recall",
"audience_id": "00000000-0000-0000-0000-000000000101",
"audience_label": "Finance operators",
"author": "agent:weekly-reviewer",
"agent_authored": true,
"created_at": "2026-07-20T09:00:00Z",
"updated_at": "2026-07-20T09:00:00Z"
}
}
Delete hypothesis
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Authored positive, negative, or neutral observations. Findings may stand alone, attach to an existing Experiment, or imply one from supplied subjects.
List findings
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/findings \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"findings": [
{
"id": "00000000-0000-0000-0000-000000000b01",
"hypothesis_id": "00000000-0000-0000-0000-000000000801",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"body": "The faster founder opening improved click-through.",
"signal": "positive",
"finding_at": "2026-07-23T17:00:00Z",
"supersedes_finding_id": null,
"superseded": false,
"author": "agent:weekly-reviewer",
"agent_authored": true,
"created_at": "2026-07-23T17:00:00Z",
"updated_at": "2026-07-23T17:00:00Z"
}
]
}
Create finding
{
"finding": {
"body": "The faster founder opening improved click-through.",
"signal": "positive",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"window_end": "2026-07-23T17:00:00Z"
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/findings \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"finding":{"body":"The faster founder opening improved click-through.","signal":"positive","experiment_id":"00000000-0000-0000-0000-000000000901","window_end":"2026-07-23T17:00:00Z"}}'
{
"finding": {
"id": "00000000-0000-0000-0000-000000000b01",
"hypothesis_id": "00000000-0000-0000-0000-000000000801",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"body": "The faster founder opening improved click-through.",
"signal": "positive",
"finding_at": "2026-07-23T17:00:00Z",
"supersedes_finding_id": null,
"superseded": false,
"author": "agent:weekly-reviewer",
"agent_authored": true,
"created_at": "2026-07-23T17:00:00Z",
"updated_at": "2026-07-23T17:00:00Z"
}
}
Get finding
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/findings/YOUR_FINDING_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"finding": {
"id": "00000000-0000-0000-0000-000000000b01",
"hypothesis_id": "00000000-0000-0000-0000-000000000801",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"body": "The faster founder opening improved click-through.",
"signal": "positive",
"finding_at": "2026-07-23T17:00:00Z",
"supersedes_finding_id": null,
"superseded": false,
"author": "agent:weekly-reviewer",
"agent_authored": true,
"created_at": "2026-07-23T17:00:00Z",
"updated_at": "2026-07-23T17:00:00Z"
}
}
Update inferred finding signal
{
"finding": {
"signal": "positive"
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/findings/YOUR_FINDING_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"finding":{"signal":"positive"}}'
{
"finding": {
"id": "00000000-0000-0000-0000-000000000b01",
"hypothesis_id": "00000000-0000-0000-0000-000000000801",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"body": "The faster founder opening improved click-through.",
"signal": "positive",
"finding_at": "2026-07-23T17:00:00Z",
"supersedes_finding_id": null,
"superseded": false,
"author": "agent:weekly-reviewer",
"agent_authored": true,
"created_at": "2026-07-23T17:00:00Z",
"updated_at": "2026-07-23T17:00:00Z"
}
}
Optional lightweight bundles of attempts and subjects under a Hypothesis. They provide context without asserting statistical certainty.
List experiments
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"experiments": [
{
"id": "00000000-0000-0000-0000-000000000901",
"hypothesis_id": "00000000-0000-0000-0000-000000000801",
"context": "Founder narration with the offer in the first two seconds",
"state": "ongoing",
"window_start": "2026-07-20T09:00:00Z",
"window_end": null,
"author": "agent:weekly-reviewer",
"agent_authored": true,
"subjects": [
{
"id": "00000000-0000-0000-0000-000000000a01",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"name": "Founder opening",
"kind": "internal",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"ad_run_id": null,
"external_ref": null,
"created_at": "2026-07-20T09:05:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
],
"created_at": "2026-07-20T09:00:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
]
}
Open experiment
{
"experiment": {
"context": "Founder narration with the offer in the first two seconds",
"window_start": "2026-07-20T09:00:00Z",
"window_end": null
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"experiment":{"context":"Founder narration with the offer in the first two seconds","window_start":"2026-07-20T09:00:00Z","window_end":null}}'
{
"experiment": {
"id": "00000000-0000-0000-0000-000000000901",
"hypothesis_id": "00000000-0000-0000-0000-000000000801",
"context": "Founder narration with the offer in the first two seconds",
"state": "ongoing",
"window_start": "2026-07-20T09:00:00Z",
"window_end": null,
"author": "agent:weekly-reviewer",
"agent_authored": true,
"subjects": [
{
"id": "00000000-0000-0000-0000-000000000a01",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"name": "Founder opening",
"kind": "internal",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"ad_run_id": null,
"external_ref": null,
"created_at": "2026-07-20T09:05:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
],
"created_at": "2026-07-20T09:00:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
}
Get experiment
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"experiment": {
"id": "00000000-0000-0000-0000-000000000901",
"hypothesis_id": "00000000-0000-0000-0000-000000000801",
"context": "Founder narration with the offer in the first two seconds",
"state": "ongoing",
"window_start": "2026-07-20T09:00:00Z",
"window_end": null,
"author": "agent:weekly-reviewer",
"agent_authored": true,
"subjects": [
{
"id": "00000000-0000-0000-0000-000000000a01",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"name": "Founder opening",
"kind": "internal",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"ad_run_id": null,
"external_ref": null,
"created_at": "2026-07-20T09:05:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
],
"created_at": "2026-07-20T09:00:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
}
Update experiment context or window
{
"experiment": {
"context": "Founder narration with the offer in the first two seconds",
"window_start": "2026-07-20T09:00:00Z",
"window_end": null
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"experiment":{"context":"Founder narration with the offer in the first two seconds","window_start":"2026-07-20T09:00:00Z","window_end":null}}'
{
"experiment": {
"id": "00000000-0000-0000-0000-000000000901",
"hypothesis_id": "00000000-0000-0000-0000-000000000801",
"context": "Founder narration with the offer in the first two seconds",
"state": "ongoing",
"window_start": "2026-07-20T09:00:00Z",
"window_end": null,
"author": "agent:weekly-reviewer",
"agent_authored": true,
"subjects": [
{
"id": "00000000-0000-0000-0000-000000000a01",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"name": "Founder opening",
"kind": "internal",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"ad_run_id": null,
"external_ref": null,
"created_at": "2026-07-20T09:05:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
],
"created_at": "2026-07-20T09:00:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
}
Delete experiment
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
List experiment subjects
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID/subjects \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"subjects": [
{
"id": "00000000-0000-0000-0000-000000000a01",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"name": "Founder opening",
"kind": "internal",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"ad_run_id": null,
"external_ref": null,
"created_at": "2026-07-20T09:05:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
]
}
Add experiment subject
{
"subject": {
"name": "Founder opening",
"creative_composition_id": "00000000-0000-0000-0000-000000000401"
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID/subjects \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"subject":{"name":"Founder opening","creative_composition_id":"00000000-0000-0000-0000-000000000401"}}'
{
"subject": {
"id": "00000000-0000-0000-0000-000000000a01",
"experiment_id": "00000000-0000-0000-0000-000000000901",
"name": "Founder opening",
"kind": "internal",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"ad_run_id": null,
"external_ref": null,
"created_at": "2026-07-20T09:05:00Z",
"updated_at": "2026-07-20T09:05:00Z"
}
}
Remove experiment subject
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/hypotheses/YOUR_HYPOTHESIS_ID/experiments/YOUR_EXPERIMENT_ID/subjects/YOUR_EXPERIMENT_SUBJECT_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Uploaded brand, product, and media files that generated or composed ads can use.
List assets
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"assets": [
{
"id": "00000000-0000-0000-0000-000000000501",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"asset_type": "logo",
"source": "upload",
"status": "ready",
"filename": "launchpad-logo.png",
"content_type": "image/png",
"byte_size": 34721,
"width": 1024,
"height": 1024,
"duration_seconds": null,
"description": "Primary product logo",
"metadata": {
"source": "brand kit"
},
"license_metadata": {
"usage": "owned"
},
"created_at": "2026-06-19T12:00:00Z",
"updated_at": "2026-06-19T12:00:00Z",
"file_url": "http://localhost:3000/api/v1/projects/launchpad/assets/00000000-0000-0000-0000-000000000501/file"
}
]
}
Upload an asset
{
"asset": {
"file": "@./logo.png",
"asset_type": "logo",
"description": "Primary product logo",
"metadata": {
"source": "brand kit"
},
"license_metadata": {
"usage": "owned"
}
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -F "asset[file]=@./logo.png" \ -F "asset[asset_type]=logo" \ -F "asset[description]=Primary product logo" \ -F "asset[metadata][source]=brand kit" \ -F "asset[license_metadata][usage]=owned"
{
"asset": {
"id": "00000000-0000-0000-0000-000000000501",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"asset_type": "logo",
"source": "upload",
"status": "ready",
"filename": "launchpad-logo.png",
"content_type": "image/png",
"byte_size": 34721,
"width": 1024,
"height": 1024,
"duration_seconds": null,
"description": "Primary product logo",
"metadata": {
"source": "brand kit"
},
"license_metadata": {
"usage": "owned"
},
"created_at": "2026-06-19T12:00:00Z",
"updated_at": "2026-06-19T12:00:00Z",
"file_url": "http://localhost:3000/api/v1/projects/launchpad/assets/00000000-0000-0000-0000-000000000501/file"
}
}
Get asset
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets/YOUR_ASSET_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"asset": {
"id": "00000000-0000-0000-0000-000000000501",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"asset_type": "logo",
"source": "upload",
"status": "ready",
"filename": "launchpad-logo.png",
"content_type": "image/png",
"byte_size": 34721,
"width": 1024,
"height": 1024,
"duration_seconds": null,
"description": "Primary product logo",
"metadata": {
"source": "brand kit"
},
"license_metadata": {
"usage": "owned"
},
"created_at": "2026-06-19T12:00:00Z",
"updated_at": "2026-06-19T12:00:00Z",
"file_url": "http://localhost:3000/api/v1/projects/launchpad/assets/00000000-0000-0000-0000-000000000501/file"
}
}
Update asset metadata
{
"asset": {
"asset_type": "logo",
"filename": "launchpad-logo.png",
"description": "Primary product logo",
"metadata": {
"source": "brand kit"
},
"license_metadata": {
"usage": "owned"
}
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets/YOUR_ASSET_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"asset":{"asset_type":"logo","filename":"launchpad-logo.png","description":"Primary product logo","metadata":{"source":"brand kit"},"license_metadata":{"usage":"owned"}}}'
{
"asset": {
"id": "00000000-0000-0000-0000-000000000501",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"asset_type": "logo",
"source": "upload",
"status": "ready",
"filename": "launchpad-logo.png",
"content_type": "image/png",
"byte_size": 34721,
"width": 1024,
"height": 1024,
"duration_seconds": null,
"description": "Primary product logo",
"metadata": {
"source": "brand kit"
},
"license_metadata": {
"usage": "owned"
},
"created_at": "2026-06-19T12:00:00Z",
"updated_at": "2026-06-19T12:00:00Z",
"file_url": "http://localhost:3000/api/v1/projects/launchpad/assets/00000000-0000-0000-0000-000000000501/file"
}
}
Delete asset
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets/YOUR_ASSET_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Download raw asset file
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/assets/YOUR_ASSET_ID/file \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Generated creative outputs. Ads can have many external runs when the same creative is distributed in different platforms, campaigns, or ad sets.
/ads
List ads across the account
curl https://trygrowthchicken.com/api/v1/ads \
-H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"ads": [
{
"id": "00000000-0000-0000-0000-000000000401",
"slug": "summer-sale",
"project_id": "00000000-0000-0000-0000-000000000001",
"name": "LaunchPad - Ship campaigns in minutes",
"status": "generating",
"ready": false,
"generating": true,
"failed": false,
"output": "video",
"output_label": "Video ad",
"style": {
"category": "template",
"template_key": "poster_hero"
},
"editable_copy": {
"headline": "Ship campaigns in minutes"
},
"remix": {
"available": false,
"targets": [],
"elements": []
},
"audience_id": "00000000-0000-0000-0000-000000000101",
"platform_aspect": "9:16",
"placements": [
"instagram_story",
"feed_portrait",
"square",
"landscape"
],
"music": {
"asset_id": "00000000-0000-0000-0000-000000000501",
"filename": "launchpad-music-1.mp3",
"provider": "suno",
"duration_seconds": 5.0
},
"tags": [
"launch",
"winner"
],
"external_identifiers": {
"meta_ad_id": "23851234567890123"
},
"distribution": {
"current_status": "live",
"total_runs_count": 1,
"active_runs_count": 1,
"platforms": [
"meta"
],
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54",
"conversions": 7.0,
"cpa": "6.07",
"revenue": "210.00",
"roas": "4.94"
}
},
"ad_runs": [
{
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
],
"token_cost": 163,
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z",
"url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
"poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story",
"files": [
{
"placement": "square",
"label": "Square (1:1)",
"width": 1080,
"height": 1080,
"document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"
}
],
"snapshots": []
}
]
}
List ads
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"ads": [
{
"id": "00000000-0000-0000-0000-000000000401",
"slug": "summer-sale",
"project_id": "00000000-0000-0000-0000-000000000001",
"name": "LaunchPad - Ship campaigns in minutes",
"status": "generating",
"ready": false,
"generating": true,
"failed": false,
"output": "video",
"output_label": "Video ad",
"style": {
"category": "template",
"template_key": "poster_hero"
},
"editable_copy": {
"headline": "Ship campaigns in minutes"
},
"remix": {
"available": false,
"targets": [],
"elements": []
},
"audience_id": "00000000-0000-0000-0000-000000000101",
"platform_aspect": "9:16",
"placements": [
"instagram_story",
"feed_portrait",
"square",
"landscape"
],
"music": {
"asset_id": "00000000-0000-0000-0000-000000000501",
"filename": "launchpad-music-1.mp3",
"provider": "suno",
"duration_seconds": 5.0
},
"tags": [
"launch",
"winner"
],
"external_identifiers": {
"meta_ad_id": "23851234567890123"
},
"distribution": {
"current_status": "live",
"total_runs_count": 1,
"active_runs_count": 1,
"platforms": [
"meta"
],
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54",
"conversions": 7.0,
"cpa": "6.07",
"revenue": "210.00",
"roas": "4.94"
}
},
"ad_runs": [
{
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
],
"token_cost": 163,
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z",
"url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
"poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story",
"files": [
{
"placement": "square",
"label": "Square (1:1)",
"width": 1080,
"height": 1080,
"document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"
}
],
"snapshots": []
}
]
}
Generate an ad
{
"ad": {
"output": "image",
"style_scope": "any",
"template_key": "poster_hero",
"meme_base": null,
"character_direction": null,
"prompt": "Bold launch ad highlighting the new dashboard.",
"copy": "Ship campaigns in minutes",
"copy_mode": "exact",
"audience_id": "00000000-0000-0000-0000-000000000101",
"tags": [
"launch",
"winner"
],
"variant_count": 1
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ad":{"output":"image","style_scope":"any","template_key":"poster_hero","meme_base":null,"character_direction":null,"prompt":"Bold launch ad highlighting the new dashboard.","copy":"Ship campaigns in minutes","copy_mode":"exact","audience_id":"00000000-0000-0000-0000-000000000101","tags":["launch","winner"],"variant_count":1}}'
{
"ad": {
"id": "00000000-0000-0000-0000-000000000401",
"slug": "summer-sale",
"project_id": "00000000-0000-0000-0000-000000000001",
"name": "LaunchPad - Ship campaigns in minutes",
"status": "generating",
"ready": false,
"generating": true,
"failed": false,
"output": "video",
"output_label": "Video ad",
"style": {
"category": "template",
"template_key": "poster_hero"
},
"editable_copy": {
"headline": "Ship campaigns in minutes"
},
"remix": {
"available": false,
"targets": [],
"elements": []
},
"audience_id": "00000000-0000-0000-0000-000000000101",
"platform_aspect": "9:16",
"placements": [
"instagram_story",
"feed_portrait",
"square",
"landscape"
],
"music": {
"asset_id": "00000000-0000-0000-0000-000000000501",
"filename": "launchpad-music-1.mp3",
"provider": "suno",
"duration_seconds": 5.0
},
"tags": [
"launch",
"winner"
],
"external_identifiers": {
"meta_ad_id": "23851234567890123"
},
"distribution": {
"current_status": "live",
"total_runs_count": 1,
"active_runs_count": 1,
"platforms": [
"meta"
],
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54",
"conversions": 7.0,
"cpa": "6.07",
"revenue": "210.00",
"roas": "4.94"
}
},
"ad_runs": [
{
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
],
"token_cost": 163,
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z",
"url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
"poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story",
"files": [
{
"placement": "square",
"label": "Square (1:1)",
"width": 1080,
"height": 1080,
"document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"
}
],
"snapshots": []
}
}
Get ad (poll status and asset URLs)
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"ad": {
"id": "00000000-0000-0000-0000-000000000401",
"slug": "summer-sale",
"project_id": "00000000-0000-0000-0000-000000000001",
"name": "LaunchPad - Ship campaigns in minutes",
"status": "generating",
"ready": false,
"generating": true,
"failed": false,
"output": "video",
"output_label": "Video ad",
"style": {
"category": "template",
"template_key": "poster_hero"
},
"editable_copy": {
"headline": "Ship campaigns in minutes"
},
"remix": {
"available": false,
"targets": [],
"elements": []
},
"audience_id": "00000000-0000-0000-0000-000000000101",
"platform_aspect": "9:16",
"placements": [
"instagram_story",
"feed_portrait",
"square",
"landscape"
],
"music": {
"asset_id": "00000000-0000-0000-0000-000000000501",
"filename": "launchpad-music-1.mp3",
"provider": "suno",
"duration_seconds": 5.0
},
"tags": [
"launch",
"winner"
],
"external_identifiers": {
"meta_ad_id": "23851234567890123"
},
"distribution": {
"current_status": "live",
"total_runs_count": 1,
"active_runs_count": 1,
"platforms": [
"meta"
],
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54",
"conversions": 7.0,
"cpa": "6.07",
"revenue": "210.00",
"roas": "4.94"
}
},
"ad_runs": [
{
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
],
"token_cost": 163,
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z",
"url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
"poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story",
"files": [
{
"placement": "square",
"label": "Square (1:1)",
"width": 1080,
"height": 1080,
"document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"
}
],
"snapshots": []
}
}
Edit ad captions or replace tags
{
"ad": {
"tags": [
"launch",
"winner"
],
"copy": {
"setup": "Campaign chaos",
"payoff": "Meet one clean dashboard"
}
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ad":{"tags":["launch","winner"],"copy":{"setup":"Campaign chaos","payoff":"Meet one clean dashboard"}}}'
{
"ad": {
"id": "00000000-0000-0000-0000-000000000401",
"slug": "summer-sale",
"project_id": "00000000-0000-0000-0000-000000000001",
"name": "LaunchPad - Ship campaigns in minutes",
"status": "generating",
"ready": false,
"generating": true,
"failed": false,
"output": "video",
"output_label": "Video ad",
"style": {
"category": "template",
"template_key": "poster_hero"
},
"editable_copy": {
"headline": "Ship campaigns in minutes"
},
"remix": {
"available": false,
"targets": [],
"elements": []
},
"audience_id": "00000000-0000-0000-0000-000000000101",
"platform_aspect": "9:16",
"placements": [
"instagram_story",
"feed_portrait",
"square",
"landscape"
],
"music": {
"asset_id": "00000000-0000-0000-0000-000000000501",
"filename": "launchpad-music-1.mp3",
"provider": "suno",
"duration_seconds": 5.0
},
"tags": [
"launch",
"winner"
],
"external_identifiers": {
"meta_ad_id": "23851234567890123"
},
"distribution": {
"current_status": "live",
"total_runs_count": 1,
"active_runs_count": 1,
"platforms": [
"meta"
],
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54",
"conversions": 7.0,
"cpa": "6.07",
"revenue": "210.00",
"roas": "4.94"
}
},
"ad_runs": [
{
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
],
"token_cost": 163,
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z",
"url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
"poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story",
"files": [
{
"placement": "square",
"label": "Square (1:1)",
"width": 1080,
"height": 1080,
"document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"
}
],
"snapshots": []
}
}
Delete ad
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Remix an ad
{
"remix": {
"target": "still",
"locks": [
"background",
"text:headline"
]
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/remix \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"remix":{"target":"still","locks":["background","text:headline"]}}'
{
"ad": {
"id": "00000000-0000-0000-0000-000000000401",
"slug": "summer-sale",
"project_id": "00000000-0000-0000-0000-000000000001",
"name": "LaunchPad - Ship campaigns in minutes",
"status": "generating",
"ready": false,
"generating": true,
"failed": false,
"output": "video",
"output_label": "Video ad",
"style": {
"category": "template",
"template_key": "poster_hero"
},
"editable_copy": {
"headline": "Ship campaigns in minutes"
},
"remix": {
"available": false,
"targets": [],
"elements": []
},
"audience_id": "00000000-0000-0000-0000-000000000101",
"platform_aspect": "9:16",
"placements": [
"instagram_story",
"feed_portrait",
"square",
"landscape"
],
"music": {
"asset_id": "00000000-0000-0000-0000-000000000501",
"filename": "launchpad-music-1.mp3",
"provider": "suno",
"duration_seconds": 5.0
},
"tags": [
"launch",
"winner"
],
"external_identifiers": {
"meta_ad_id": "23851234567890123"
},
"distribution": {
"current_status": "live",
"total_runs_count": 1,
"active_runs_count": 1,
"platforms": [
"meta"
],
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54",
"conversions": 7.0,
"cpa": "6.07",
"revenue": "210.00",
"roas": "4.94"
}
},
"ad_runs": [
{
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
],
"token_cost": 163,
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z",
"url": "http://localhost:3000/projects/launchpad/creative_compositions/summer-sale",
"poll_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=instagram_story",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=instagram_story",
"files": [
{
"placement": "square",
"label": "Square (1:1)",
"width": 1080,
"height": 1080,
"document_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.html?placement=square",
"video_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.mp4?placement=square",
"still_url": "http://localhost:3000/api/v1/projects/launchpad/ads/summer-sale/file.png?placement=square"
}
],
"snapshots": []
}
}
List tags on an ad
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/tags \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"tags": [
"launch",
"winner"
]
}
Add a tag to an ad
{
"tag": "winner"
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/tags \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"tag":"winner"}'
{
"tag": "winner",
"tags": [
"launch",
"winner"
]
}
Remove a tag from an ad
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/tags/YOUR_AD_ID_OR_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Download the rendered asset (mp4/png/jpg) or the editable HTML document
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/file \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
User-declared key-value pairs (e.g. meta_ad_account, google_customer, product_key) that anchor a project or an ad to the outside platforms it runs in, so performance data resolves back deterministically.
List project external identifiers
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"external_identifiers": [
{
"id": "00000000-0000-0000-0000-000000000601",
"owner": {
"type": "project",
"id": "00000000-0000-0000-0000-000000000001"
},
"key": "meta_ad_account",
"value": "act_1234567890",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
]
}
Set a project external identifier
{
"external_identifier": {
"key": "meta_ad_account",
"value": "act_1234567890"
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"external_identifier":{"key":"meta_ad_account","value":"act_1234567890"}}'
{
"external_identifier": {
"id": "00000000-0000-0000-0000-000000000601",
"owner": {
"type": "project",
"id": "00000000-0000-0000-0000-000000000001"
},
"key": "meta_ad_account",
"value": "act_1234567890",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
}
Get project external identifier
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers/YOUR_PROJECT_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"external_identifier": {
"id": "00000000-0000-0000-0000-000000000601",
"owner": {
"type": "project",
"id": "00000000-0000-0000-0000-000000000001"
},
"key": "meta_ad_account",
"value": "act_1234567890",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
}
Update project external identifier
{
"external_identifier": {
"key": "meta_ad_account",
"value": "act_1234567890"
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers/YOUR_PROJECT_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"external_identifier":{"key":"meta_ad_account","value":"act_1234567890"}}'
{
"external_identifier": {
"id": "00000000-0000-0000-0000-000000000601",
"owner": {
"type": "project",
"id": "00000000-0000-0000-0000-000000000001"
},
"key": "meta_ad_account",
"value": "act_1234567890",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
}
Delete project external identifier
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/external_identifiers/YOUR_PROJECT_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
List ad external identifiers
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"external_identifiers": [
{
"id": "00000000-0000-0000-0000-000000000601",
"owner": {
"type": "ad",
"id": "00000000-0000-0000-0000-000000000401"
},
"key": "meta_ad_id",
"value": "23851234567890123",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
]
}
Set an ad external identifier
{
"external_identifier": {
"key": "meta_ad_account",
"value": "act_1234567890"
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"external_identifier":{"key":"meta_ad_account","value":"act_1234567890"}}'
{
"external_identifier": {
"id": "00000000-0000-0000-0000-000000000601",
"owner": {
"type": "ad",
"id": "00000000-0000-0000-0000-000000000401"
},
"key": "meta_ad_id",
"value": "23851234567890123",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
}
Get ad external identifier
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers/YOUR_AD_ID_OR_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"external_identifier": {
"id": "00000000-0000-0000-0000-000000000601",
"owner": {
"type": "ad",
"id": "00000000-0000-0000-0000-000000000401"
},
"key": "meta_ad_id",
"value": "23851234567890123",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
}
Update ad external identifier
{
"external_identifier": {
"key": "meta_ad_account",
"value": "act_1234567890"
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers/YOUR_AD_ID_OR_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"external_identifier":{"key":"meta_ad_account","value":"act_1234567890"}}'
{
"external_identifier": {
"id": "00000000-0000-0000-0000-000000000601",
"owner": {
"type": "ad",
"id": "00000000-0000-0000-0000-000000000401"
},
"key": "meta_ad_id",
"value": "23851234567890123",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
}
Delete ad external identifier
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/external_identifiers/YOUR_AD_ID_OR_SLUG \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Distribution instances for an ad outside Growth Chicken. A run identifies the platform, channel, objective, external campaign/ad ids, current projected status, and rolled-up performance.
List ad runs
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"ad_runs": [
{
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
]
}
Create ad run
{
"ad_run": {
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metadata": {
"owner": "agent"
}
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ad_run":{"platform":"meta","channel":"paid_social","objective":"traffic","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metadata":{"owner":"agent"}}}'
{
"ad_run": {
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
}
Get ad run
curl https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs/YOUR_AD_RUN_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"ad_run": {
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
}
Update ad run
{
"ad_run": {
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metadata": {
"owner": "agent"
}
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs/YOUR_AD_RUN_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ad_run":{"platform":"meta","channel":"paid_social","objective":"traffic","external_account_id":"act_123","external_campaign_id":"cmp_123","external_ad_group_id":"set_123","external_ad_id":"ad_123","external_url":"https://ads.example.test/ad_123","metadata":{"owner":"agent"}}}'
{
"ad_run": {
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
}
Delete ad run
curl -X DELETE https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/runs/YOUR_AD_RUN_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Append-style facts about a run. Lifecycle observations project run status and dates; metric observations roll up performance; notes and platform snapshots preserve source context.
List ad run observations
curl https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"ad_observations": [
{
"id": "00000000-0000-0000-0000-000000000701",
"ad_run_id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"kind": "lifecycle",
"source": "agent",
"observed_at": "2026-07-06T12:00:00Z",
"effective_at": "2026-07-03T09:00:00Z",
"interval_start": null,
"interval_end": null,
"grain": null,
"currency": null,
"conversion_event": null,
"attribution": null,
"attribution_window": null,
"lifecycle_event": "activated",
"note": null,
"metrics": {},
"metadata": {
"reported_by": "agent"
},
"idempotency_key": "agent-activation-123",
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
]
}
Create ad run observation
{
"ad_observation": {
"kind": "lifecycle",
"source": "agent",
"observed_at": "2026-07-06T12:00:00Z",
"effective_at": "2026-07-03T09:00:00Z",
"lifecycle_event": "activated",
"idempotency_key": "meta:event:activate-123"
}
}
curl -X POST https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ad_observation":{"kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","lifecycle_event":"activated","idempotency_key":"meta:event:activate-123"}}'
{
"ad_observation": {
"id": "00000000-0000-0000-0000-000000000701",
"ad_run_id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"kind": "lifecycle",
"source": "agent",
"observed_at": "2026-07-06T12:00:00Z",
"effective_at": "2026-07-03T09:00:00Z",
"interval_start": null,
"interval_end": null,
"grain": null,
"currency": null,
"conversion_event": null,
"attribution": null,
"attribution_window": null,
"lifecycle_event": "activated",
"note": null,
"metrics": {},
"metadata": {
"reported_by": "agent"
},
"idempotency_key": "agent-activation-123",
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
},
"ad_run": {
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
}
Get ad run observation
curl https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations/YOUR_OBSERVATION_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
{
"ad_observation": {
"id": "00000000-0000-0000-0000-000000000701",
"ad_run_id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"kind": "lifecycle",
"source": "agent",
"observed_at": "2026-07-06T12:00:00Z",
"effective_at": "2026-07-03T09:00:00Z",
"interval_start": null,
"interval_end": null,
"grain": null,
"currency": null,
"conversion_event": null,
"attribution": null,
"attribution_window": null,
"lifecycle_event": "activated",
"note": null,
"metrics": {},
"metadata": {
"reported_by": "agent"
},
"idempotency_key": "agent-activation-123",
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
},
"ad_run": {
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
}
Update ad run observation
{
"ad_observation": {
"kind": "lifecycle",
"source": "agent",
"observed_at": "2026-07-06T12:00:00Z",
"effective_at": "2026-07-03T09:00:00Z",
"lifecycle_event": "activated",
"idempotency_key": "meta:event:activate-123"
}
}
curl -X PATCH https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations/YOUR_OBSERVATION_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ad_observation":{"kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","lifecycle_event":"activated","idempotency_key":"meta:event:activate-123"}}'
{
"ad_observation": {
"id": "00000000-0000-0000-0000-000000000701",
"ad_run_id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"kind": "lifecycle",
"source": "agent",
"observed_at": "2026-07-06T12:00:00Z",
"effective_at": "2026-07-03T09:00:00Z",
"interval_start": null,
"interval_end": null,
"grain": null,
"currency": null,
"conversion_event": null,
"attribution": null,
"attribution_window": null,
"lifecycle_event": "activated",
"note": null,
"metrics": {},
"metadata": {
"reported_by": "agent"
},
"idempotency_key": "agent-activation-123",
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
},
"ad_run": {
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
}
Delete ad run observation
curl -X DELETE https://trygrowthchicken.com/api/v1/ad_runs/YOUR_AD_RUN_ID/observations/YOUR_OBSERVATION_ID \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN"
Create observation and find or create its run
{
"ad_observation": {
"platform": "meta",
"channel": "paid_social",
"external_account_id": "account_123",
"external_ad_id": "ad_123",
"kind": "lifecycle",
"source": "agent",
"observed_at": "2026-07-06T12:00:00Z",
"effective_at": "2026-07-03T09:00:00Z",
"lifecycle_event": "activated",
"idempotency_key": "meta:event:activate-123"
}
}
curl -X POST https://trygrowthchicken.com/api/v1/projects/YOUR_PROJECT_SLUG/ads/YOUR_AD_ID_OR_SLUG/observations \ -H "Authorization: Bearer $GROWTH_CHICKEN_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"ad_observation":{"platform":"meta","channel":"paid_social","external_account_id":"account_123","external_ad_id":"ad_123","kind":"lifecycle","source":"agent","observed_at":"2026-07-06T12:00:00Z","effective_at":"2026-07-03T09:00:00Z","lifecycle_event":"activated","idempotency_key":"meta:event:activate-123"}}'
{
"ad_observation": {
"id": "00000000-0000-0000-0000-000000000701",
"ad_run_id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"kind": "lifecycle",
"source": "agent",
"observed_at": "2026-07-06T12:00:00Z",
"effective_at": "2026-07-03T09:00:00Z",
"interval_start": null,
"interval_end": null,
"grain": null,
"currency": null,
"conversion_event": null,
"attribution": null,
"attribution_window": null,
"lifecycle_event": "activated",
"note": null,
"metrics": {},
"metadata": {
"reported_by": "agent"
},
"idempotency_key": "agent-activation-123",
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
},
"ad_run": {
"id": "00000000-0000-0000-0000-000000000601",
"creative_composition_id": "00000000-0000-0000-0000-000000000401",
"project_id": "00000000-0000-0000-0000-000000000001",
"user_id": "00000000-0000-0000-0000-000000000301",
"platform": "meta",
"channel": "paid_social",
"objective": "traffic",
"current_status": "live",
"first_live_at": "2026-07-03T09:00:00Z",
"last_live_at": "2026-07-03T09:00:00Z",
"ended_at": null,
"last_observed_at": "2026-07-06T12:00:00Z",
"source": "agent",
"external_account_id": "act_123",
"external_campaign_id": "cmp_123",
"external_ad_group_id": "set_123",
"external_ad_id": "ad_123",
"external_url": "https://ads.example.test/ad_123",
"metrics_summary": {
"spend": "42.50",
"currency": "USD",
"impressions": 12000,
"clicks": 188,
"ctr": "1.57",
"cpc": "0.23",
"cpm": "3.54"
},
"health": {
"trend": "steady",
"recent_ctr": "1.57",
"previous_ctr": "1.50",
"change_pct": 4.7,
"z_score": 0.82,
"statistically_significant": false,
"recent_impressions": 12000,
"previous_impressions": 11000,
"as_of": "2026-07-05",
"availability": {
"frequency": false
}
},
"cost": {
"cpc": "0.23",
"cpm": "3.54",
"currency": "USD"
},
"delivery": {
"status": "healthy",
"share_pct": 62.5,
"impressions": 12000,
"ad_group_impressions": 19200,
"as_of": "2026-07-05",
"window_start": "2026-07-03",
"window_end": "2026-07-05",
"availability": {
"available": true
}
},
"rank": {
"metric": "cpa",
"position": 1,
"group_size": 2,
"percentile": 100
},
"metadata": {
"owner": "agent"
},
"observations_count": 2,
"created_at": "2026-07-06T12:00:00Z",
"updated_at": "2026-07-06T12:00:00Z"
}
}
No endpoints match your search.