Report creatives

Creatives by spend over a range, with what they cost and earned across the ads that show them, and signs of fatigue.

Paged. Platform-reported and Voidhash-measured numbers stay in separate objects; measured numbers need project:analytics:read and are null without it. Money is in minor units of currency, rates are decimals. Safe to repeat. Needs project:ads:read.

Guide: Ads reports

Authorization

AuthorizationBearer <token>

A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.

In: header

Path parameters

projectId*string

The project's id, proj_.... A secret key works only in the project it belongs to.

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

from*string

The first day of the range, YYYY-MM-DD in timezone.

to*string

The last day of the range, inclusive, YYYY-MM-DD in timezone. A report spans at most 366 days.

currency?|

ISO 4217 code to report money in. Defaults to the project's reporting currency, else the connected accounts' when they share one, else USD.

timezone?|

IANA time zone the days are cut in, such as Europe/Prague. Defaults to the connected accounts' when they share one, else UTC.

environment?|

Environment measured purchases are read from: production, sandbox (store sandboxes such as TestFlight) or test (simulated purchases). Defaults to production.

formats?array<>|

Only creatives of these formats: image, video or carousel.

search?|

Only those whose name contains this text, ignoring case, or whose id is exactly it. At most 200 characters.

limit?|

Creatives per page, from 1 to 100; defaults to 50.

cursor?|

Where to resume: the pageInfo.endCursor of the previous page.

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/reports/creatives" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "from": "2026-03-01",    "to": "2026-03-31",    "timezone": "Europe/Prague",    "formats": [      "video"    ]  }'

{  "data": [    {      "id": "120210000000000004",      "name": "Spring trial - 15s workout",      "format": "video",      "videoDurationSeconds": 15,      "cardCount": null,      "thumbnailUrl": "https://scontent.xx.fbcdn.net/v/t15.5256-10/...",      "copy": {        "primaryTexts": [          "Train smarter this spring. Start your 7-day free trial."        ],        "headlines": [          "Your plan, your pace"        ],        "descriptions": []      },      "media": [        {          "type": "video",          "imageUrl": "https://scontent.xx.fbcdn.net/v/t15.5256-10/...",          "imageHash": null,          "videoId": "987654321098765",          "thumbnailUrl": "https://scontent.xx.fbcdn.net/v/t15.5256-10/...",          "headline": null,          "description": null,          "link": null        }      ],      "callToAction": "SIGN_UP",      "landingUrl": "https://example.app/start/spring",      "adCount": 1,      "deliveryStatus": "delivering",      "adsInDeliveryStatus": 1,      "spend": 482350,      "ctr": 0.015,      "hookRate": 0.3125,      "platformRoas": 0.6244,      "roas": 0.5461,      "costPerPayer": 2871,      "frequency": 1.84,      "fatigue": null,      "platformUrl": "https://adsmanager.facebook.com/adsmanager/manage/ads?act=1234567890&selected_ad_ids=120210000000000003"    }  ],  "pageInfo": {    "endCursor": null,    "hasNextPage": false  },  "from": "2026-03-01",  "to": "2026-03-31",  "currency": "USD",  "timezone": "Europe/Prague",  "environment": "production",  "hasMeasuredAccess": true,  "warnings": [],  "provisionalFrom": "2026-03-25"}

{  "error": {    "type": "invalid_request",    "code": "invalid_report",    "message": "Europe/Prag is not an IANA time zone."  }}

{  "error": {    "type": "unauthenticated",    "code": "invalid_api_key",    "message": "This secret key is not valid."  }}

{  "error": {    "type": "permission_denied",    "code": "permission_denied",    "message": "Insufficient permissions."  }}

{  "error": {    "type": "not_found",    "code": "project_not_found",    "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.",    "param": "projectId"  }}

{  "error": {    "type": "internal",    "code": "internal_error",    "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing."  }}

Response body

`application/json`

Errors

Status	`type`	`code`	When
400	`invalid_request`	`invalid_report`	For a range or time zone it cannot report on.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

More in Ads

Something wrong or missing on this page? Tell us by email or on Discord.

Report creatives

Creatives by spend over a range, with what they cost and earned across the ads that show them, and signs of fatigue.

Guide: Ads reports

Authorization

AuthorizationBearer <token>

A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.

In: header

Path parameters

projectId*string

The project's id, proj_.... A secret key works only in the project it belongs to.

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

from*string

The first day of the range, YYYY-MM-DD in timezone.

to*string

The last day of the range, inclusive, YYYY-MM-DD in timezone. A report spans at most 366 days.

currency?|

ISO 4217 code to report money in. Defaults to the project's reporting currency, else the connected accounts' when they share one, else USD.

timezone?|

IANA time zone the days are cut in, such as Europe/Prague. Defaults to the connected accounts' when they share one, else UTC.

environment?|

Environment measured purchases are read from: production, sandbox (store sandboxes such as TestFlight) or test (simulated purchases). Defaults to production.

formats?array<>|

Only creatives of these formats: image, video or carousel.

search?|

Only those whose name contains this text, ignoring case, or whose id is exactly it. At most 200 characters.

limit?|

Creatives per page, from 1 to 100; defaults to 50.

cursor?|

Where to resume: the pageInfo.endCursor of the previous page.

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/reports/creatives" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "from": "2026-03-01",    "to": "2026-03-31",    "timezone": "Europe/Prague",    "formats": [      "video"    ]  }'

{  "data": [    {      "id": "120210000000000004",      "name": "Spring trial - 15s workout",      "format": "video",      "videoDurationSeconds": 15,      "cardCount": null,      "thumbnailUrl": "https://scontent.xx.fbcdn.net/v/t15.5256-10/...",      "copy": {        "primaryTexts": [          "Train smarter this spring. Start your 7-day free trial."        ],        "headlines": [          "Your plan, your pace"        ],        "descriptions": []      },      "media": [        {          "type": "video",          "imageUrl": "https://scontent.xx.fbcdn.net/v/t15.5256-10/...",          "imageHash": null,          "videoId": "987654321098765",          "thumbnailUrl": "https://scontent.xx.fbcdn.net/v/t15.5256-10/...",          "headline": null,          "description": null,          "link": null        }      ],      "callToAction": "SIGN_UP",      "landingUrl": "https://example.app/start/spring",      "adCount": 1,      "deliveryStatus": "delivering",      "adsInDeliveryStatus": 1,      "spend": 482350,      "ctr": 0.015,      "hookRate": 0.3125,      "platformRoas": 0.6244,      "roas": 0.5461,      "costPerPayer": 2871,      "frequency": 1.84,      "fatigue": null,      "platformUrl": "https://adsmanager.facebook.com/adsmanager/manage/ads?act=1234567890&selected_ad_ids=120210000000000003"    }  ],  "pageInfo": {    "endCursor": null,    "hasNextPage": false  },  "from": "2026-03-01",  "to": "2026-03-31",  "currency": "USD",  "timezone": "Europe/Prague",  "environment": "production",  "hasMeasuredAccess": true,  "warnings": [],  "provisionalFrom": "2026-03-25"}

{  "error": {    "type": "invalid_request",    "code": "invalid_report",    "message": "Europe/Prag is not an IANA time zone."  }}

{  "error": {    "type": "unauthenticated",    "code": "invalid_api_key",    "message": "This secret key is not valid."  }}

{  "error": {    "type": "permission_denied",    "code": "permission_denied",    "message": "Insufficient permissions."  }}

{  "error": {    "type": "not_found",    "code": "project_not_found",    "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.",    "param": "projectId"  }}

{  "error": {    "type": "internal",    "code": "internal_error",    "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing."  }}

Response body

`application/json`

Errors

Status	`type`	`code`	When
400	`invalid_request`	`invalid_report`	For a range or time zone it cannot report on.

It can also fail with the errors every operation shares, such as unauthenticated; see Errors.

More in Ads

Something wrong or missing on this page? Tell us by email or on Discord.

Report creatives

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

Report creatives

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`