Contents

Get an Ad

Retrieves a single ad by its unique identifier.

URL

GET https://api.ads.apple.com/v1/ads/{id}

Path Parameters

NameTypeDescription
id Requiredstring

Header Parameters

NameTypeDescription
X-Ap-Context Requiredstring

Response Codes

StatusReasonTypeDescription
200OK
Content-Type: application/json
AdResponse
400Bad Request
Content-Type: application/json
ErrorResponse
401Unauthorized
Content-Type: application/json
ErrorResponse
403Forbidden
Content-Type: application/json
ErrorResponse
404Not Found
Content-Type: application/json
ErrorResponse
429Too Many Requests
Content-Type: application/json
ErrorResponse
500Internal Server Error
Content-Type: application/json
ErrorResponse

Discussion

This endpoint retrieves a single ad by its ID. The response includes systemStatus, displayStatus, systemStatusReasons, and systemStatusLimitingReasons. To diagnose why an ad may not be delivering, use these fields together. See Ads Endpoints for the full status field semantics.

The displayStatus field resolves to one of the following values:

Value

Description

RUNNING

The ad is actively serving impressions.

PAUSED

The advertiser paused the ad at the ad level (status: PAUSED).

ON_HOLD

The ad is on hold due to an ad-level condition.

AD_GROUP_ON_HOLD

The parent ad group is on hold.

CAMPAIGN_ON_HOLD

The parent campaign is on hold.

LIMITED

The ad is serving, but one or more factors restrict delivery.

PROCESSING

The system is processing the ad, or Apple is reviewing its ad creative.

DELETED

The advertiser deleted the ad.

When systemStatus is NOT_RUNNING, check the following causes:

Cause

Description

Creative pending review

Apple has not yet approved the ad creative associated with this ad. displayStatus is PROCESSING.

Creative rejected

Apple rejected the ad creative (INVALID). The ad will not serve until the advertiser associates a new ad creative via a new ad.

Ad paused

status: PAUSED on the ad itself.

Ad group paused

The advertiser has paused the parent ad group, or the system has put it on hold.

Campaign paused

The advertiser has paused the parent campaign, or the system has put it on hold.

Keep the following constraints in mind when reading a GET response:

Constraint

Detail

Deleted ads are returned

The system still returns a deleted ad with deleted: true. It does not remove the record from GET by ID responses.

Use systemStatusReasons for diagnostics

The systemStatusReasons array identifies specific causes when systemStatus is NOT_RUNNING.

creativeId and adGroupId are read-only

These fields are immutable. The system sets them at creation and returns them on every GET response.

To list all ads, use the query endpoint

GET /v1/ads/{id} returns a single record. To list or filter multiple ads, use POST /v1/ads/query.

Payload Examples

See Also