> ## 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.

# Fetch insight

> Return performance metrics for an ad over a date range

## Overview

Return performance metrics for an ad. Targeter uses this to populate campaign stats in the app.

Dates are inclusive `YYYY-MM-DD`. Omit both `from_date` and `to_date` to return lifetime totals from the ad `start_date` through today.

Metrics should match what Targeter already shows on campaigns: impressions, clicks, spend, CPM, CPC, CTR, reach, frequency, conversions, and video quartiles when the creative is video.

## 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>

### Query Parameters

<ParamField query="from_date" type="string">
  Start of the reporting window (inclusive)
</ParamField>

<ParamField query="to_date" type="string">
  End of the reporting window (inclusive)
</ParamField>

### Example Request

```bash theme={null}
curl "https://publisher.example.com/v1/ads/ad_9pL2wR/insights?from_date=2026-08-01&to_date=2026-08-19" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Response

### Success (200)

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

<ResponseField name="insights" type="object">
  Aggregated metrics for the requested window
</ResponseField>

<ResponseField name="insights.impressions" type="integer">
  Total ad impressions
</ResponseField>

<ResponseField name="insights.clicks" type="integer">
  Total ad clicks
</ResponseField>

<ResponseField name="insights.spend" type="number">
  Amount spent in `insights.currency`
</ResponseField>

<ResponseField name="insights.currency" type="string">
  ISO 4217 currency code
</ResponseField>

<ResponseField name="insights.cpm" type="number">
  Cost per 1,000 impressions
</ResponseField>

<ResponseField name="insights.cpc" type="number">
  Cost per click
</ResponseField>

<ResponseField name="insights.ctr" type="number">
  Click-through rate (`clicks / impressions`)
</ResponseField>

<ResponseField name="insights.reach" type="integer">
  Unique people reached
</ResponseField>

<ResponseField name="insights.frequency" type="number">
  Average impressions per person reached
</ResponseField>

<ResponseField name="insights.conversion" type="integer">
  Total conversions
</ResponseField>

<ResponseField name="insights.cost_per_conversion" type="number">
  Average cost per conversion
</ResponseField>

<ResponseField name="insights.video_views" type="object">
  Video completion quartiles (`p25`, `p50`, `p75`, `p100`). Omit when the ad has no video.
</ResponseField>

<ResponseField name="insights.from_date" type="string">
  Start of the window actually returned
</ResponseField>

<ResponseField name="insights.to_date" type="string">
  End of the window actually returned
</ResponseField>

```json theme={null}
{
    "ad_id": "ad_9pL2wR",
    "insights": {
        "impressions": 12500,
        "clicks": 340,
        "spend": 1500,
        "currency": "NOK",
        "cpm": 120.0,
        "cpc": 4.41,
        "ctr": 0.0272,
        "reach": 8200,
        "frequency": 1.52,
        "conversion": 28,
        "cost_per_conversion": 53.57,
        "video_views": {
            "p25": 5469,
            "p50": 4031,
            "p75": 2472,
            "p100": 1031
        },
        "from_date": "2026-08-01",
        "to_date": "2026-08-19"
    }
}
```

<Note>
  Return zeros rather than omitting core counters (`impressions`, `clicks`, `spend`) when the ad has not delivered yet.
</Note>

## Error Responses

### 400 - Invalid request payload

```json theme={null}
{
    "error": "to_date must be on or after from_date"
}
```

### 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}/insights
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}/insights:
    get:
      tags:
        - Insights
      summary: Fetch insight
      description: >-
        Return performance metrics for an ad over an inclusive date range. Dates
        use `YYYY-MM-DD`. Omit both dates to return lifetime totals from
        `start_date` through today.
      operationId: fetchInsight
      parameters:
        - $ref: '#/components/parameters/AdId'
        - name: from_date
          in: query
          required: false
          description: Start of the reporting window (inclusive). ISO 8601 date.
          schema:
            type: string
            format: date
          example: '2026-08-01'
        - name: to_date
          in: query
          required: false
          description: End of the reporting window (inclusive). ISO 8601 date.
          schema:
            type: string
            format: date
          example: '2026-08-19'
      responses:
        '200':
          description: Insights for the requested window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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:
    InsightResponse:
      type: object
      required:
        - ad_id
        - insights
      properties:
        ad_id:
          type: string
          example: ad_9pL2wR
        insights:
          type: object
          properties:
            impressions:
              type: integer
              example: 12500
            clicks:
              type: integer
              example: 340
            spend:
              type: number
              description: Amount spent in the ad currency
              example: 1500
            currency:
              type: string
              example: NOK
            cpm:
              type: number
              example: 120
            cpc:
              type: number
              example: 4.41
            ctr:
              type: number
              example: 0.0272
            reach:
              type: integer
              example: 8200
            frequency:
              type: number
              example: 1.52
            conversion:
              type: integer
              example: 28
            cost_per_conversion:
              type: number
              example: 53.57
            video_views:
              $ref: '#/components/schemas/VideoViewQuartiles'
            from_date:
              type: string
              format: date
              example: '2026-08-01'
            to_date:
              type: string
              format: date
              example: '2026-08-19'
    VideoViewQuartiles:
      type: object
      properties:
        p25:
          type: integer
          example: 5469
        p50:
          type: integer
          example: 4031
        p75:
          type: integer
          example: 2472
        p100:
          type: integer
          example: 1031
    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:
    BadRequest:
      description: Invalid request payload
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid request payload
            details:
              - path:
                  - name
                message: 'Invalid input: expected string, received undefined'
    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>`.

````