Report ad changes

What changed in the project's ads over a period of up to 7 days, as the hourly syncs found it: decisions (objects created, turned on, paused or removed, and budget and bid strategy changes) with their values before and after; what each campaign, ad group or ad delivered between syncs, normally per hour; and the platform's revisions of days that had already ended, mostly conversions attributed late.

Everything is as the platform reports it, in each ad account's currency (minor units) and time zone. History starts when Voidhash began keeping it (historySince). The most recent 2,000 deliveries and revisions are kept, with a too_many_objects warning when there were more. 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.

since*string

Start of the period, inclusive, as an ISO 8601 timestamp.

until?|

End of the period, exclusive, as an ISO 8601 timestamp; defaults to now. A report spans at most 7 days.

level?|

What delivery and revisions are added up by: campaign (the default), ad_group or ad.

campaignIds?array<string>|

Only these campaigns, or the ad groups and ads in them, by the platform's ids. At most 100.

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/reports/changes" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "since": "2026-03-14T00:00:00.000Z",    "level": "campaign"  }'

{  "since": "2026-03-14T00:00:00.000Z",  "until": "2026-03-14T10:30:00.000Z",  "level": "campaign",  "accounts": [    {      "id": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "name": "Acme Fitness",      "platform": "meta",      "currency": "USD",      "timezone": "Europe/Prague",      "syncedAt": "2026-03-14T10:00:12.000Z",      "historySince": "2026-03-01T09:00:40.000Z"    }  ],  "decisions": [    {      "kind": "budget",      "changedAt": "2026-03-14T08:52:00.000Z",      "detectedAt": "2026-03-14T09:00:11.000Z",      "adAccountId": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "level": "campaign",      "id": "120210000000000001",      "name": "Spring trial",      "campaignId": "120210000000000001",      "adGroupId": null,      "currency": "USD",      "before": {        "budget": {          "period": "daily",          "amount": 15000        }      },      "after": {        "budget": {          "period": "daily",          "amount": 20000        }      }    }  ],  "delivery": [    {      "readAt": "2026-03-14T10:00:12.000Z",      "adAccountId": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "level": "campaign",      "id": "120210000000000001",      "name": "Spring trial",      "campaignId": "120210000000000001",      "adGroupId": null,      "currency": "USD",      "spend": 1184,      "impressions": 1502,      "clicks": 41,      "linkClicks": 23,      "results": [        {          "type": "landing_page_view",          "label": null,          "count": 18        }      ],      "conversions": [        {          "kind": "start_trial",          "count": 1,          "value": null        }      ]    }  ],  "revisions": [    {      "readAt": "2026-03-14T10:00:12.000Z",      "date": "2026-03-12",      "adAccountId": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "level": "campaign",      "id": "120210000000000001",      "name": "Spring trial",      "campaignId": "120210000000000001",      "adGroupId": null,      "currency": "USD",      "spend": 0,      "impressions": 0,      "clicks": 0,      "linkClicks": 0,      "results": [],      "conversions": [        {          "kind": "purchase",          "count": 2,          "value": 1998        }      ]    }  ],  "warnings": []}

{  "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 period 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 ad changes

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.

since*string

Start of the period, inclusive, as an ISO 8601 timestamp.

until?|

End of the period, exclusive, as an ISO 8601 timestamp; defaults to now. A report spans at most 7 days.

level?|

What delivery and revisions are added up by: campaign (the default), ad_group or ad.

campaignIds?array<string>|

Only these campaigns, or the ad groups and ads in them, by the platform's ids. At most 100.

Examples

curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/ads/reports/changes" \  -H "Authorization: Bearer vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "since": "2026-03-14T00:00:00.000Z",    "level": "campaign"  }'

{  "since": "2026-03-14T00:00:00.000Z",  "until": "2026-03-14T10:30:00.000Z",  "level": "campaign",  "accounts": [    {      "id": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "name": "Acme Fitness",      "platform": "meta",      "currency": "USD",      "timezone": "Europe/Prague",      "syncedAt": "2026-03-14T10:00:12.000Z",      "historySince": "2026-03-01T09:00:40.000Z"    }  ],  "decisions": [    {      "kind": "budget",      "changedAt": "2026-03-14T08:52:00.000Z",      "detectedAt": "2026-03-14T09:00:11.000Z",      "adAccountId": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "level": "campaign",      "id": "120210000000000001",      "name": "Spring trial",      "campaignId": "120210000000000001",      "adGroupId": null,      "currency": "USD",      "before": {        "budget": {          "period": "daily",          "amount": 15000        }      },      "after": {        "budget": {          "period": "daily",          "amount": 20000        }      }    }  ],  "delivery": [    {      "readAt": "2026-03-14T10:00:12.000Z",      "adAccountId": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "level": "campaign",      "id": "120210000000000001",      "name": "Spring trial",      "campaignId": "120210000000000001",      "adGroupId": null,      "currency": "USD",      "spend": 1184,      "impressions": 1502,      "clicks": 41,      "linkClicks": 23,      "results": [        {          "type": "landing_page_view",          "label": null,          "count": 18        }      ],      "conversions": [        {          "kind": "start_trial",          "count": 1,          "value": null        }      ]    }  ],  "revisions": [    {      "readAt": "2026-03-14T10:00:12.000Z",      "date": "2026-03-12",      "adAccountId": "ad_acct_k3m9x2c7v1b8n4q6w0e5r2t7",      "level": "campaign",      "id": "120210000000000001",      "name": "Spring trial",      "campaignId": "120210000000000001",      "adGroupId": null,      "currency": "USD",      "spend": 0,      "impressions": 0,      "clicks": 0,      "linkClicks": 0,      "results": [],      "conversions": [        {          "kind": "purchase",          "count": 2,          "value": 1998        }      ]    }  ],  "warnings": []}

{  "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 period 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 ad changes

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

Report ad changes

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`