> ## Documentation Index
> Fetch the complete documentation index at: https://docs.targeter.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Get ad status

> Return the current delivery status of an ad

## Overview

Return the current delivery status so Targeter can sync campaign state. Targeter polls this while a campaign is live and after pause, resume, or review.

### Status values

| Status           | Meaning                                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `draft`          | Created but not yet submitted for delivery                                                            |
| `pending_review` | Waiting on publisher or policy review                                                                 |
| `scheduled`      | Approved; `start_date` is in the future                                                               |
| `active`         | Currently delivering                                                                                  |
| `paused`         | Delivery stopped by Targeter or the publisher                                                         |
| `completed`      | Flight ended or budget exhausted                                                                      |
| `rejected`       | Review failed; the ad will not deliver                                                                |
| `error`          | Publisher-side failure; include enough in `error` payloads for Targeter to retry or surface the issue |

## Request

### Headers

* `Authorization: Bearer {token}` (required)

### Path Parameters

<ParamField path="ad_id" type="string" required>
  Publisher-generated ad id returned from [Create ad](/integrations/ads/create)
</ParamField>

### Example Request

```bash theme={null}
curl "https://publisher.example.com/v1/ads/ad_9pL2wR/status" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Response

### Success (200)

<ResponseField name="ad_id" type="string">
  Publisher-generated ad id
</ResponseField>

<ResponseField name="status" type="string">
  Current delivery status
</ResponseField>

<ResponseField name="updated_at" type="string">
  UTC timestamp of the last status change
</ResponseField>

```json theme={null}
{
    "ad_id": "ad_9pL2wR",
    "status": "active",
    "updated_at": "2026-08-20T06:00:00Z"
}
```

## Error Responses

### 401 - Unauthorized

```json theme={null}
{
    "error": "Missing or invalid Authorization header"
}
```

### 404 - Ad not found

```json theme={null}
{
    "error": "Ad not found"
}
```

### 500 - Server Error

```json theme={null}
{
    "error": "Unexpected server error. Please try again later."
}
```


## OpenAPI

````yaml integrations/openapi.json GET /ads/{ad_id}/status
openapi: 3.1.0
info:
  title: Targeter Ideal Publisher API
  description: >-
    Contract Targeter expects from publisher and media platforms it creates ads
    on and fetches insights from. Implement these endpoints so Targeter can
    manage offices, ads, and reporting against your system.
  version: 1.0.0
  contact:
    name: Targeter Integration Support
servers:
  - url: https://{publisher_host}/v1
    description: Publisher API host (provided during integration setup)
    variables:
      publisher_host:
        default: publisher.example.com
security:
  - BearerAuth: []
tags:
  - name: Offices
    description: Broker or advertiser offices that ads are billed and attributed to
  - name: Ads
    description: Create, update, pause, resume, and delete ads
  - name: Insights
    description: Performance reporting for ads Targeter has created
  - name: Platforms
    description: Publisher channels available for delivery
paths:
  /ads/{ad_id}/status:
    get:
      tags:
        - Ads
      summary: Get ad status
      description: >-
        Return the current delivery status of an ad, plus timestamps Targeter
        uses to sync campaign state.
      operationId: getAdStatus
      parameters:
        - $ref: '#/components/parameters/AdId'
      responses:
        '200':
          description: Current ad status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/AdNotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    AdId:
      name: ad_id
      in: path
      required: true
      description: Publisher-generated ad id returned from `POST /ads`
      schema:
        type: string
      example: ad_9pL2wR
  schemas:
    AdStatusResponse:
      type: object
      required:
        - ad_id
        - status
      properties:
        ad_id:
          type: string
          example: ad_9pL2wR
        status:
          $ref: '#/components/schemas/AdStatus'
        updated_at:
          type: string
          format: date-time
          example: '2026-08-19T09:00:00Z'
    AdStatus:
      type: string
      description: Delivery status of the ad
      enum:
        - draft
        - pending_review
        - scheduled
        - active
        - paused
        - completed
        - rejected
        - error
      example: active
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
          example: Missing required field
        details:
          type: array
          description: Per-field validation issues
          items:
            type: object
            required:
              - message
            properties:
              path:
                type: array
                items:
                  type: string
                example:
                  - material
                  - target_url
              message:
                type: string
                example: Target URL is required
  responses:
    Unauthorized:
      description: Missing Authorization header, or invalid or expired token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingHeader:
              value:
                error: Missing or invalid Authorization header
            invalidToken:
              value:
                error: Invalid or expired token
    AdNotFound:
      description: Ad not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Ad not found
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unexpected server error. Please try again later.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token issued to Targeter during integration setup. Send as
        `Authorization: Bearer <token>`.

````