List ads

List ads

Lists synced ads, ordered by name; campaignId or adGroupId lists those under one.

Filter by adAccountId, status, deliveryStatus, destination, or search (the name, ignoring case, or the exact id). 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.

Query parameters

cursor?string

Where the page starts: the pageInfo.endCursor of the previous page. Omit it for the first page.

limit?integer

How many items to return, from 1 to 100. Defaults to 50.

Range1 <= value <= 100

adAccountId?string

Only objects of this connected account, ad_acct_...; an account the project has not connected fails with ad_account_not_connected.

status?string

Only objects with this status set on the platform: on, paused or removed.

Value in

"on"
"paused"
"removed"

deliveryStatus?string

Only objects with this delivery status, such as delivering or rejected.

Value in

"delivering"
"learning"
"learning_limited"
"not_delivering"
"in_review"
"rejected"
"paused"
"off_by_parent"
"scheduled"
"ended"
"account_issue"

destination?string

Only objects whose ads send people here: website, app_store, web_to_app or mixed.

Value in

"website"
"app_store"
"web_to_app"
"mixed"

search?string

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

Lengthlength <= 200

campaignId?string

Only those of this campaign, by the platform's id.

adGroupId?string

Only the ads of this ad group, by the platform's id.

Examples

curl -X GET "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/ads?adGroupId=120210000000000002" \  -H "Authorization: Bearer vh_sk_..."

{  "data": [    {      "projectId": "proj_tz4a98xxat96iws9zmbrgj3a",      "adAccountId": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "platform": "meta",      "status": "on",      "deliveryStatus": "delivering",      "deliveryReasons": [],      "destination": "web_to_app",      "budget": {        "amount": 20000,        "currency": "USD",        "period": "daily",        "level": "campaign"      },      "startsAt": "2026-02-28T23:00:00.000Z",      "endsAt": null,      "createdAt": "2026-02-27T14:10:00.000Z",      "updatedAt": "2026-03-01T09:30:00.000Z",      "syncedAt": "2026-03-14T10:00:12.000Z",      "id": "120210000000000003",      "name": "Spring trial - 15s workout",      "platformUrl": "https://adsmanager.facebook.com/adsmanager/manage/ads?act=1234567890&selected_ad_ids=120210000000000003",      "campaignId": "120210000000000001",      "adGroupId": "120210000000000002",      "creativeId": "120210000000000004",      "landingUrl": "https://example.app/start/spring",      "urlParameters": "utm_source=facebook&campaign_id={{campaign.id}}&adset_id={{adset.id}}&ad_id={{ad.id}}",      "missingTrackingParameters": []    }  ],  "pageInfo": {    "endCursor": null,    "hasNextPage": false  }}

{  "error": {    "type": "invalid_request",    "code": "ad_account_not_connected",    "message": "Ad account ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7 is not connected to this project.",    "param": "adAccountId"  }}

{  "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`	`ad_account_not_connected`	For a filter naming an account the project has not connected.

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.

List ads

Lists synced ads, ordered by name; campaignId or adGroupId lists those under one.

Filter by adAccountId, status, deliveryStatus, destination, or search (the name, ignoring case, or the exact id). 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.

Query parameters

cursor?string

Where the page starts: the pageInfo.endCursor of the previous page. Omit it for the first page.

limit?integer

How many items to return, from 1 to 100. Defaults to 50.

Range1 <= value <= 100

adAccountId?string

Only objects of this connected account, ad_acct_...; an account the project has not connected fails with ad_account_not_connected.

status?string

Only objects with this status set on the platform: on, paused or removed.

Value in

"on"
"paused"
"removed"

deliveryStatus?string

Only objects with this delivery status, such as delivering or rejected.

Value in

"delivering"
"learning"
"learning_limited"
"not_delivering"
"in_review"
"rejected"
"paused"
"off_by_parent"
"scheduled"
"ended"
"account_issue"

destination?string

Only objects whose ads send people here: website, app_store, web_to_app or mixed.

Value in

"website"
"app_store"
"web_to_app"
"mixed"

search?string

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

Lengthlength <= 200

campaignId?string

Only those of this campaign, by the platform's id.

adGroupId?string

Only the ads of this ad group, by the platform's id.

Examples

curl -X GET "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/ads?adGroupId=120210000000000002" \  -H "Authorization: Bearer vh_sk_..."

{  "data": [    {      "projectId": "proj_tz4a98xxat96iws9zmbrgj3a",      "adAccountId": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "platform": "meta",      "status": "on",      "deliveryStatus": "delivering",      "deliveryReasons": [],      "destination": "web_to_app",      "budget": {        "amount": 20000,        "currency": "USD",        "period": "daily",        "level": "campaign"      },      "startsAt": "2026-02-28T23:00:00.000Z",      "endsAt": null,      "createdAt": "2026-02-27T14:10:00.000Z",      "updatedAt": "2026-03-01T09:30:00.000Z",      "syncedAt": "2026-03-14T10:00:12.000Z",      "id": "120210000000000003",      "name": "Spring trial - 15s workout",      "platformUrl": "https://adsmanager.facebook.com/adsmanager/manage/ads?act=1234567890&selected_ad_ids=120210000000000003",      "campaignId": "120210000000000001",      "adGroupId": "120210000000000002",      "creativeId": "120210000000000004",      "landingUrl": "https://example.app/start/spring",      "urlParameters": "utm_source=facebook&campaign_id={{campaign.id}}&adset_id={{adset.id}}&ad_id={{ad.id}}",      "missingTrackingParameters": []    }  ],  "pageInfo": {    "endCursor": null,    "hasNextPage": false  }}

{  "error": {    "type": "invalid_request",    "code": "ad_account_not_connected",    "message": "Ad account ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7 is not connected to this project.",    "param": "adAccountId"  }}

{  "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`	`ad_account_not_connected`	For a filter naming an account the project has not connected.

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.

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

List ads

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`