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

# GET /api/v1/campaigns/fetch — Retrieve Ad Campaigns

> Retrieve targeted ad campaigns by placement, location, and device. Returns an array of campaign objects with id, title, destinationUrl, and status fields.

Use this endpoint to retrieve available ad campaigns for a specific placement in your application. You pass targeting parameters — placement, location, and device type — and the API returns a list of campaigns that match. Call this endpoint server-side before rendering an ad slot so you can select and display the right campaign for the current user context.

## Endpoint

```
GET https://ads.enslive.live/api/v1/campaigns/fetch
```

## Request example

```bash theme={null}
curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?limit=10&placement=header_banner&location=US&device=mobile" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Query parameters

<ParamField query="placement" type="string" required>
  The target placement ID that identifies where the ad will appear in your layout. Examples: `header_banner`, `article_inline`, `sidebar_top`. See [Ad Placements](/concepts/placements) for the full list of supported values.
</ParamField>

<ParamField query="limit" type="integer" default="10">
  The number of campaigns to return. Defaults to `10`. Maximum value is `100`. Use a higher limit to batch-fetch campaigns and reduce the number of API calls your integration makes.
</ParamField>

<ParamField query="location" type="string">
  The ISO 3166-1 alpha-2 country code representing the user's geographic location. Examples: `US`, `GB`, `FR`. When provided, the API filters campaigns to those targeted at the specified country.
</ParamField>

<ParamField query="device" type="string">
  The device type of the current user. Accepted values: `mobile`, `desktop`, `tablet`. When provided, the API filters campaigns to those targeted at the specified device type.
</ParamField>

## Response

### 200 — Success

The response includes a `status` field, a `data` array of campaign objects, and a `count` of returned campaigns.

```json theme={null}
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "title": "Summer Sale Campaign",
      "description": "Limited time offer",
      "category": "retail",
      "destinationUrl": "https://example.com/summer",
      "status": "running",
      "createdAt": "2026-04-17T00:00:00Z"
    }
  ],
  "count": 1
}
```

<ResponseField name="status" type="string">
  Always `"success"` for a successful response.
</ResponseField>

<ResponseField name="count" type="integer">
  The number of campaign objects returned in the `data` array.
</ResponseField>

<ResponseField name="data" type="array">
  Array of campaign objects matching the requested placement and targeting parameters.

  <Expandable title="Campaign object fields">
    <ResponseField name="id" type="integer">
      Unique identifier for the campaign. Use this value when calling the impression and click tracking endpoints.
    </ResponseField>

    <ResponseField name="title" type="string">
      The display title of the campaign.
    </ResponseField>

    <ResponseField name="description" type="string">
      A short description of the campaign's offer or message.
    </ResponseField>

    <ResponseField name="category" type="string">
      The content category the campaign belongs to (e.g., `retail`, `technology`, `health`).
    </ResponseField>

    <ResponseField name="destinationUrl" type="string">
      The URL users should be directed to when they interact with the campaign.
    </ResponseField>

    <ResponseField name="status" type="string">
      The current status of the campaign. A value of `"running"` means the campaign is active and eligible for display.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp indicating when the campaign was created.
    </ResponseField>
  </Expandable>
</ResponseField>

### 400 — Bad Request

Returned when a required parameter is missing or a parameter value is invalid.

```json theme={null}
{
  "status": "error",
  "message": "placement parameter is required"
}
```

### 401 — Unauthorized

Returned when the `Authorization` header is missing or the API key is invalid.

```json theme={null}
{
  "status": "error",
  "message": "unauthorized"
}
```