Foreplay Public API

https://public.api.foreplay.co/docs
Admin
This API empowers users to programmatically search, filter, and analyze a vast database of ads and...
Tokens:3,850
Snippets:25
Trust Score:9.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Fetch Brands

Source: https://public.api.foreplay.co/docs

This example demonstrates how to fetch a list of brands using the Spyder endpoint. It includes query parameters for pagination and requires an Authorization header.

```APIDOC
## GET /api/spyder/brands

### Description
Fetches a list of brands, with options for pagination.

### Method
GET

### Endpoint
https://public.api.foreplay.co/api/spyder/brands

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - The number of records to skip before starting to collect the result set.
- **limit** (integer) - Optional - The numbers of records to return. Default is 10.

### Request Example
```bash
curl -X GET "https://public.api.foreplay.co/api/spyder/brands?offset=0&limit=10" \
  -H "Authorization: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **data** (array) - An array of brand objects.
  - **id** (string) - The unique identifier for the brand.
  - **name** (string) - The name of the brand.
- **metadata** (object) - Contains metadata about the request.
  - **success** (boolean) - Indicates if the request was successful.
  - **status_code** (integer) - The HTTP status code of the response.
  - **count** (integer) - The number of records returned.

#### Response Example
```json
{
  "data": [
    {
      "id": "brand_123456",
      "name": "Example Brand Inc."
    }
  ],
  "metadata": {
    "success": true,
    "status_code": 200,
    "count": 1
  }
}
```
```

--------------------------------

### Example Error Response (401 Unauthorized)

Source: https://public.api.foreplay.co/docs

This is an example of an error response when authentication fails due to an invalid or missing API key. It includes metadata about the request and specific error details.

```json
{
  "metadata": {
    "success": false,
    "message": "Authentication failed.",
    "status_code": 401,
    "processed_at": 1756488402833
  },
  "error": {
    "message": "Invalid or missing API key"
  },
  "data": []
}
```

--------------------------------

### Fetch Brands List (Python)

Source: https://public.api.foreplay.co/docs

This Python example uses the requests library to fetch the first 10 brands. The API key is passed in the headers, and query parameters are set for offset and limit.

```python
import requests

# Fetches the first 10 brands from the Spyder endpoint.
r = requests.get(
    "https://public.api.foreplay.co/api/spyder/brands",
    params={\"offset\": 0, \"limit\": 10},
    headers={\"Authorization\": \"YOUR_API_KEY\"},
)

```

--------------------------------

### API Response Example

Source: https://public.api.foreplay.co/docs

A successful API response will contain a JSON object with 'data' and 'metadata' fields. The 'data' field includes the requested information, and 'metadata' provides request details.

```json
{
  "data": [
    {
      "id": "brand_123456",
      "name": "Example Brand Inc.",
      // ... other brand details
    }
  ],
  "metadata": {
    "success": true,
    "status_code": 200,
    "count": 1
    // ... other metadata
  }
}

```

--------------------------------

### Get SwipeFile Ads with cURL

Source: https://public.api.foreplay.co/docs

Use this cURL command to retrieve a user's swipefile ads. Ensure you have the correct Bearer token for authentication. The query parameters allow for filtering and pagination of results.

```shell
curl -X GET \
  'https://public.api.foreplay.co/api/swipefile/ads?start_date=2024-11-12%2000:00:00&end_date=2024-11-12%2023:59:59&live=true&display_format=video&publisher_platform=facebook&niches=%5B%22accessories%22%5D&market_target=b2c&languages=en&video_duration_min=5&video_duration_max=60&running_duration_min_days=1&running_duration_max_days=7&offset=0&limit=10&order=saved_newest' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

--------------------------------

### Fetch Brands List (JavaScript)

Source: https://public.api.foreplay.co/docs

This JavaScript snippet demonstrates how to fetch the first 10 brands using the fetch API. The API key must be included in the Authorization header.

```javascript
// Fetches the first 10 brands from the Spyder endpoint.
await fetch("https://public.api.foreplay.co/api/spyder/brands?offset=0&limit=10", {
  headers: { Authorization: "YOUR_API_KEY" }
});

```

--------------------------------

### Fetch Brands List (cURL)

Source: https://public.api.foreplay.co/docs

Use this cURL command to fetch the first 10 brands from the Spyder endpoint. Ensure your API key is included in the Authorization header.

```bash
# This command requests the first 10 brands from the Spyder endpoint.
curl -X GET "https://public.api.foreplay.co/api/spyder/brands?offset=0&limit=10" 
  -H "Authorization: YOUR_API_KEY"

```

--------------------------------

### API Key Authentication Header

Source: https://public.api.foreplay.co/docs

Every request to the API requires your key to be sent in the `Authorization` header. Replace `YOUR_API_KEY` with your generated key.

```text
Authorization: YOUR_API_KEY

```

--------------------------------

### SwipeFile Ads

Source: https://public.api.foreplay.co/docs

Retrieve a user's swipefile ads, which are all saved ads within their swipefile. Supports filtering by date, status, and various other parameters.

```APIDOC
## GET /api/swipefile/ads

### Description
Get user's swipefile ads, all saved ads in swipefile.

### Method
GET

### Endpoint
https://public.api.foreplay.co/api/swipefile/ads

### Query Parameters
- **start_date** (string) - Optional - Example: 2024-11-12 00:00:00
- **end_date** (string) - Optional - Example: 2024-11-12 23:59:59
- **live** (boolean) - Optional - Example: true
- **display_format** (string) - Optional - Example: video
- **publisher_platform** (string) - Optional - Example: facebook
- **niches** (array) - Optional - Example: [ "accessories" ]
- **market_target** (string) - Optional - Example: b2c
- **languages** (string) - Optional - Example: en
- **video_duration_min** (integer) - Optional - Example: 5
- **video_duration_max** (integer) - Optional - Example: 60
- **running_duration_min_days** (integer) - Optional - Example: 1
- **running_duration_max_days** (integer) - Optional - Example: 7
- **offset** (integer) - Optional - Example: 0
- **limit** (integer) - Optional - Example: 10
- **order** (string) - Optional - Example: saved_newest

### Request Example
```bash
curl -X GET \
  'https://public.api.foreplay.co/api/swipefile/ads?start_date=2024-11-12%2000%3A00%3A00&end_date=2024-11-12%2023%3A59%3A59&live=true&display_format=video&publisher_platform=facebook&niches=%5B%22accessories%22%5D&market_target=b2c&languages=en&video_duration_min=5&video_duration_max=60&running_duration_min_days=1&running_duration_max_days=7&offset=0&limit=10&order=saved_newest' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

### Response
#### Success Response (200)
- **ads** (array) - List of swipefile ads.
  - **ad_id** (string) - The unique identifier for the ad.
  - **created_at** (string) - Timestamp when the ad was saved.
  - **updated_at** (string) - Timestamp when the ad was last updated.
  - **deleted_at** (string) - Timestamp when the ad was deleted, if applicable.
  - **user_id** (string) - The ID of the user who saved the ad.
  - **ad_content** (object) - Contains the details of the ad content.
    - **id** (string) - The unique identifier for the ad content.
    - **campaign_id** (string) - The ID of the campaign the ad belongs to.
    - **account_id** (string) - The ID of the ad account.
    - **created_time** (string) - Timestamp when the ad was created.
    - **status** (string) - The current status of the ad.
    - **name** (string) - The name of the ad.
    - **objective** (string) - The objective of the ad campaign.
    - **preview_url** (string) - URL to preview the ad.
    - **thumbnail_url** (string) - URL for the ad's thumbnail.
    - **video_id** (string) - The ID of the associated video.
    - **video_url** (string) - URL of the ad's video.
    - **video_duration_seconds** (integer) - Duration of the video in seconds.
    - **publisher_platform** (string) - The platform where the ad is published.
    - **insights** (object) - Performance metrics for the ad.
      - **impressions** (integer) - Number of times the ad was shown.
      - **clicks** (integer) - Number of clicks on the ad.
      - **spend** (number) - Amount spent on the ad.
      - **conversions** (integer) - Number of conversions generated by the ad.
      - **reach** (integer) - Number of unique users who saw the ad.
      - **frequency** (number) - Average number of times users saw the ad.
      - **video_play_at_25_percent** (integer) - Number of times the video was played to 25%.
      - **video_play_at_50_percent** (integer) - Number of times the video was played to 50%.
      - **video_play_at_75_percent** (integer) - Number of times the video was played to 75%.
      - **video_play_at_100_percent** (integer) - Number of times the video was played to 100%.
      - **video_avg_percent_watched** (number) - Average percentage of the video watched.
      - **video_avg_time_watched** (number) - Average time spent watching the video.
    - **account_name** (string) - The name of the ad account.
    - **campaign_name** (string) - The name of the campaign.
    - **adset_name** (string) - The name of the ad set.
    - **market_target** (string) - The target market for the ad.
    - **languages** (array) - Languages targeted by the ad.
    - **niches** (array) - Niches targeted by the ad.
    - **running_duration_days** (integer) - Duration the ad has been running in days.

#### Response Example
```json
{
  "ads": [
    {
      "ad_id": "ad_123",
      "created_at": "2024-11-12T10:00:00Z",
      "updated_at": "2024-11-12T10:00:00Z",
      "deleted_at": null,
      "user_id": "user_abc",
      "ad_content": {
        "id": "ad_content_456",
        "campaign_id": "campaign_789",
        "account_id": "account_xyz",
        "created_time": "2024-11-11T09:00:00Z",
        "status": "ACTIVE",
        "name": "Example Ad Name",
        "objective": "LINK_CLICKS",
        "preview_url": "https://example.com/preview/ad_456",
        "thumbnail_url": "https://example.com/thumbnail/ad_456.jpg",
        "video_id": "video_111",
        "video_url": "https://example.com/video/ad_456.mp4",
        "video_duration_seconds": 30,
        "publisher_platform": "facebook",
        "insights": {
          "impressions": 1000,
          "clicks": 50,
          "spend": 25.50,
          "conversions": 5,
          "reach": 800,
          "frequency": 1.25,
          "video_play_at_25_percent": 700,
          "video_play_at_50_percent": 500,
          "video_play_at_75_percent": 300,
          "video_play_at_100_percent": 100,
          "video_avg_percent_watched": 0.45,
          "video_avg_time_watched": 13.5
        },
        "account_name": "Example Account",
        "campaign_name": "Example Campaign",
        "adset_name": "Example Ad Set",
        "market_target": "b2c",
        "languages": ["en"],
        "niches": ["accessories"],
        "running_duration_days": 3
      }
    }
  ]
}
```
```
Tokens:
Raw