List ads

curl --request GET \
  --url https://api.aisa.one/apis/v1/ads \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.aisa.one/apis/v1/ads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/ads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/ads"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/ads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "ads": [
    {
      "_id": "<string>",
      "adSetName": "<string>",
      "adType": "boost",
      "bidAmount": 123,
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "budget": {
        "amount": 123,
        "daily": 123,
        "lifetime": 123,
        "pacing": "<string>",
        "type": "daily"
      },
      "campaignName": "<string>",
      "configuredStatus": "<string>",
      "costType": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "creative": {
        "adFormat": "<string>",
        "assetGroup": {},
        "assetGroupResourceName": "<string>",
        "assetResourceName": "<string>",
        "assets": {},
        "bodies": [
          "<string>"
        ],
        "body": "<string>",
        "callToAction": "<string>",
        "carouselCards": [
          {}
        ],
        "catalog": {},
        "creativeFeatures": {},
        "creativeId": "<string>",
        "description": "<string>",
        "descriptions": [
          "<string>"
        ],
        "effectiveInstagramMediaId": "<string>",
        "effectiveObjectStoryId": "<string>",
        "finalUrls": [
          "<string>"
        ],
        "googleDescription": "<string>",
        "googleHeadline": "<string>",
        "headline": "<string>",
        "headlines": [
          "<string>"
        ],
        "imageHash": "<string>",
        "imageUrl": "<string>",
        "instagramPermalinkUrl": "<string>",
        "instagramUserId": "<string>",
        "instagramVideoFallback": {},
        "isServing": true,
        "leadGenFormId": "<string>",
        "linkUrl": "<string>",
        "mediaUrls": [
          "<string>"
        ],
        "objectStoryId": "<string>",
        "objectType": "<string>",
        "pageId": "<string>",
        "pinterestDescription": "<string>",
        "pinterestImageUrl": "<string>",
        "pinterestTitle": "<string>",
        "servingHoldReasons": [
          "<string>"
        ],
        "thumbnailUrl": "<string>",
        "urlTags": "<string>",
        "videoId": "<string>",
        "videoUrl": "<string>",
        "whatsappPhoneNumber": "<string>",
        "youtubeVideoIds": [
          "<string>"
        ]
      },
      "creativeType": "carousel",
      "goal": "engagement",
      "isExternal": true,
      "metrics": {
        "actionValues": {},
        "actions": {},
        "allConversions": 123,
        "clicks": 123,
        "conversions": 123,
        "costPerAction": {},
        "costPerConversion": 123,
        "costPerThruplay": 123,
        "cpc": 123,
        "cpm": 123,
        "ctr": 123,
        "engagement": 123,
        "engagementBreakdown": {},
        "funnel": {},
        "impressions": 123,
        "inlineLinkClickCtr": 123,
        "inlineLinkClicks": 123,
        "lastSyncedAt": "2023-11-07T05:31:56Z",
        "outboundClicks": 123,
        "outboundClicksCtr": 123,
        "purchaseValue": 123,
        "reach": 123,
        "roas": 123,
        "spend": 123,
        "uniqueClicks": 123,
        "uniqueCtr": 123,
        "video2SecWatchedActions": 123,
        "video30SecWatchedActions": 123,
        "video6SecFocusedViews": 123,
        "video6SecWatchedActions": 123,
        "videoAvgTimeWatchedActions": 123,
        "videoP100WatchedActions": 123,
        "videoP25WatchedActions": 123,
        "videoP50WatchedActions": 123,
        "videoP75WatchedActions": 123,
        "videoP95WatchedActions": 123,
        "videoPlayActions": 123,
        "videoThruplayWatchedActions": 123
      },
      "name": "<string>",
      "optimizationGoal": "<string>",
      "platform": "facebook",
      "platformAdAccountId": "<string>",
      "platformAdAccountName": "<string>",
      "platformAdId": "<string>",
      "platformAdSetId": "<string>",
      "platformCampaignId": "<string>",
      "platformCreatedAt": "2023-11-07T05:31:56Z",
      "platformObjective": "<string>",
      "promotedObject": {
        "application_id": "<string>",
        "custom_event_type": "<string>",
        "page_id": "<string>",
        "pixel_id": "<string>",
        "product_set_id": "<string>"
      },
      "rejectionReason": "<string>",
      "reviewStatus": "in_review",
      "roasAverageFloor": 123,
      "schedule": {
        "endDate": "2023-11-07T05:31:56Z",
        "startDate": "2023-11-07T05:31:56Z"
      },
      "servingStatuses": [
        "<string>"
      ],
      "status": "active",
      "synced": true,
      "targeting": {},
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "backfillPending": true,
  "pagination": {
    "limit": 123,
    "page": 123,
    "pages": 123,
    "total": 123
  }
}

{
  "backfillPending": true,
  "ads": [
    {
      "_id": "<string>",
      "adSetName": "<string>",
      "adType": "boost",
      "bidAmount": 123,
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "budget": {
        "amount": 123,
        "daily": 123,
        "lifetime": 123,
        "pacing": "<string>",
        "type": "daily"
      },
      "campaignName": "<string>",
      "configuredStatus": "<string>",
      "costType": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "creative": {
        "adFormat": "<string>",
        "assetGroup": {},
        "assetGroupResourceName": "<string>",
        "assetResourceName": "<string>",
        "assets": {},
        "bodies": [
          "<string>"
        ],
        "body": "<string>",
        "callToAction": "<string>",
        "carouselCards": [
          {}
        ],
        "catalog": {},
        "creativeFeatures": {},
        "creativeId": "<string>",
        "description": "<string>",
        "descriptions": [
          "<string>"
        ],
        "effectiveInstagramMediaId": "<string>",
        "effectiveObjectStoryId": "<string>",
        "finalUrls": [
          "<string>"
        ],
        "googleDescription": "<string>",
        "googleHeadline": "<string>",
        "headline": "<string>",
        "headlines": [
          "<string>"
        ],
        "imageHash": "<string>",
        "imageUrl": "<string>",
        "instagramPermalinkUrl": "<string>",
        "instagramUserId": "<string>",
        "instagramVideoFallback": {},
        "isServing": true,
        "leadGenFormId": "<string>",
        "linkUrl": "<string>",
        "mediaUrls": [
          "<string>"
        ],
        "objectStoryId": "<string>",
        "objectType": "<string>",
        "pageId": "<string>",
        "pinterestDescription": "<string>",
        "pinterestImageUrl": "<string>",
        "pinterestTitle": "<string>",
        "servingHoldReasons": [
          "<string>"
        ],
        "thumbnailUrl": "<string>",
        "urlTags": "<string>",
        "videoId": "<string>",
        "videoUrl": "<string>",
        "whatsappPhoneNumber": "<string>",
        "youtubeVideoIds": [
          "<string>"
        ]
      },
      "creativeType": "carousel",
      "goal": "engagement",
      "isExternal": true,
      "metrics": {
        "actionValues": {},
        "actions": {},
        "allConversions": 123,
        "clicks": 123,
        "conversions": 123,
        "costPerAction": {},
        "costPerConversion": 123,
        "costPerThruplay": 123,
        "cpc": 123,
        "cpm": 123,
        "ctr": 123,
        "engagement": 123,
        "engagementBreakdown": {},
        "funnel": {},
        "impressions": 123,
        "inlineLinkClickCtr": 123,
        "inlineLinkClicks": 123,
        "lastSyncedAt": "2023-11-07T05:31:56Z",
        "outboundClicks": 123,
        "outboundClicksCtr": 123,
        "purchaseValue": 123,
        "reach": 123,
        "roas": 123,
        "spend": 123,
        "uniqueClicks": 123,
        "uniqueCtr": 123,
        "video2SecWatchedActions": 123,
        "video30SecWatchedActions": 123,
        "video6SecFocusedViews": 123,
        "video6SecWatchedActions": 123,
        "videoAvgTimeWatchedActions": 123,
        "videoP100WatchedActions": 123,
        "videoP25WatchedActions": 123,
        "videoP50WatchedActions": 123,
        "videoP75WatchedActions": 123,
        "videoP95WatchedActions": 123,
        "videoPlayActions": 123,
        "videoThruplayWatchedActions": 123
      },
      "name": "<string>",
      "optimizationGoal": "<string>",
      "platform": "facebook",
      "platformAdAccountId": "<string>",
      "platformAdAccountName": "<string>",
      "platformAdId": "<string>",
      "platformAdSetId": "<string>",
      "platformCampaignId": "<string>",
      "platformCreatedAt": "2023-11-07T05:31:56Z",
      "platformObjective": "<string>",
      "promotedObject": {
        "application_id": "<string>",
        "custom_event_type": "<string>",
        "page_id": "<string>",
        "pixel_id": "<string>",
        "product_set_id": "<string>"
      },
      "rejectionReason": "<string>",
      "reviewStatus": "in_review",
      "roasAverageFloor": 123,
      "schedule": {
        "endDate": "2023-11-07T05:31:56Z",
        "startDate": "2023-11-07T05:31:56Z"
      },
      "servingStatuses": [
        "<string>"
      ],
      "status": "active",
      "synced": true,
      "targeting": {},
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "limit": 123,
    "page": 123,
    "pages": 123,
    "total": 123
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "retryHint": "<string>",
    "retryable": true,
    "type": "<string>"
  }
}

AIsa Ads

List ads

Ad Campaigns. Read only. Lists your ads with their performance over a date range, including ads created directly in each platform's ads manager. Returns a paginated list of ads with metrics computed over an optional date range. Use source=all to include externally-synced ads from platform ad managers. If no date range is provided, it defaults to the last 90 days. The date range is capped at 730 days max. ### History  A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ.

GET

https://api.aisa.one

apis

ads

List ads

curl --request GET \
  --url https://api.aisa.one/apis/v1/ads \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.aisa.one/apis/v1/ads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aisa.one/apis/v1/ads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aisa.one/apis/v1/ads"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aisa.one/apis/v1/ads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "ads": [
    {
      "_id": "<string>",
      "adSetName": "<string>",
      "adType": "boost",
      "bidAmount": 123,
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "budget": {
        "amount": 123,
        "daily": 123,
        "lifetime": 123,
        "pacing": "<string>",
        "type": "daily"
      },
      "campaignName": "<string>",
      "configuredStatus": "<string>",
      "costType": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "creative": {
        "adFormat": "<string>",
        "assetGroup": {},
        "assetGroupResourceName": "<string>",
        "assetResourceName": "<string>",
        "assets": {},
        "bodies": [
          "<string>"
        ],
        "body": "<string>",
        "callToAction": "<string>",
        "carouselCards": [
          {}
        ],
        "catalog": {},
        "creativeFeatures": {},
        "creativeId": "<string>",
        "description": "<string>",
        "descriptions": [
          "<string>"
        ],
        "effectiveInstagramMediaId": "<string>",
        "effectiveObjectStoryId": "<string>",
        "finalUrls": [
          "<string>"
        ],
        "googleDescription": "<string>",
        "googleHeadline": "<string>",
        "headline": "<string>",
        "headlines": [
          "<string>"
        ],
        "imageHash": "<string>",
        "imageUrl": "<string>",
        "instagramPermalinkUrl": "<string>",
        "instagramUserId": "<string>",
        "instagramVideoFallback": {},
        "isServing": true,
        "leadGenFormId": "<string>",
        "linkUrl": "<string>",
        "mediaUrls": [
          "<string>"
        ],
        "objectStoryId": "<string>",
        "objectType": "<string>",
        "pageId": "<string>",
        "pinterestDescription": "<string>",
        "pinterestImageUrl": "<string>",
        "pinterestTitle": "<string>",
        "servingHoldReasons": [
          "<string>"
        ],
        "thumbnailUrl": "<string>",
        "urlTags": "<string>",
        "videoId": "<string>",
        "videoUrl": "<string>",
        "whatsappPhoneNumber": "<string>",
        "youtubeVideoIds": [
          "<string>"
        ]
      },
      "creativeType": "carousel",
      "goal": "engagement",
      "isExternal": true,
      "metrics": {
        "actionValues": {},
        "actions": {},
        "allConversions": 123,
        "clicks": 123,
        "conversions": 123,
        "costPerAction": {},
        "costPerConversion": 123,
        "costPerThruplay": 123,
        "cpc": 123,
        "cpm": 123,
        "ctr": 123,
        "engagement": 123,
        "engagementBreakdown": {},
        "funnel": {},
        "impressions": 123,
        "inlineLinkClickCtr": 123,
        "inlineLinkClicks": 123,
        "lastSyncedAt": "2023-11-07T05:31:56Z",
        "outboundClicks": 123,
        "outboundClicksCtr": 123,
        "purchaseValue": 123,
        "reach": 123,
        "roas": 123,
        "spend": 123,
        "uniqueClicks": 123,
        "uniqueCtr": 123,
        "video2SecWatchedActions": 123,
        "video30SecWatchedActions": 123,
        "video6SecFocusedViews": 123,
        "video6SecWatchedActions": 123,
        "videoAvgTimeWatchedActions": 123,
        "videoP100WatchedActions": 123,
        "videoP25WatchedActions": 123,
        "videoP50WatchedActions": 123,
        "videoP75WatchedActions": 123,
        "videoP95WatchedActions": 123,
        "videoPlayActions": 123,
        "videoThruplayWatchedActions": 123
      },
      "name": "<string>",
      "optimizationGoal": "<string>",
      "platform": "facebook",
      "platformAdAccountId": "<string>",
      "platformAdAccountName": "<string>",
      "platformAdId": "<string>",
      "platformAdSetId": "<string>",
      "platformCampaignId": "<string>",
      "platformCreatedAt": "2023-11-07T05:31:56Z",
      "platformObjective": "<string>",
      "promotedObject": {
        "application_id": "<string>",
        "custom_event_type": "<string>",
        "page_id": "<string>",
        "pixel_id": "<string>",
        "product_set_id": "<string>"
      },
      "rejectionReason": "<string>",
      "reviewStatus": "in_review",
      "roasAverageFloor": 123,
      "schedule": {
        "endDate": "2023-11-07T05:31:56Z",
        "startDate": "2023-11-07T05:31:56Z"
      },
      "servingStatuses": [
        "<string>"
      ],
      "status": "active",
      "synced": true,
      "targeting": {},
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "backfillPending": true,
  "pagination": {
    "limit": 123,
    "page": 123,
    "pages": 123,
    "total": 123
  }
}

{
  "backfillPending": true,
  "ads": [
    {
      "_id": "<string>",
      "adSetName": "<string>",
      "adType": "boost",
      "bidAmount": 123,
      "bidStrategy": "LOWEST_COST_WITHOUT_CAP",
      "budget": {
        "amount": 123,
        "daily": 123,
        "lifetime": 123,
        "pacing": "<string>",
        "type": "daily"
      },
      "campaignName": "<string>",
      "configuredStatus": "<string>",
      "costType": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "creative": {
        "adFormat": "<string>",
        "assetGroup": {},
        "assetGroupResourceName": "<string>",
        "assetResourceName": "<string>",
        "assets": {},
        "bodies": [
          "<string>"
        ],
        "body": "<string>",
        "callToAction": "<string>",
        "carouselCards": [
          {}
        ],
        "catalog": {},
        "creativeFeatures": {},
        "creativeId": "<string>",
        "description": "<string>",
        "descriptions": [
          "<string>"
        ],
        "effectiveInstagramMediaId": "<string>",
        "effectiveObjectStoryId": "<string>",
        "finalUrls": [
          "<string>"
        ],
        "googleDescription": "<string>",
        "googleHeadline": "<string>",
        "headline": "<string>",
        "headlines": [
          "<string>"
        ],
        "imageHash": "<string>",
        "imageUrl": "<string>",
        "instagramPermalinkUrl": "<string>",
        "instagramUserId": "<string>",
        "instagramVideoFallback": {},
        "isServing": true,
        "leadGenFormId": "<string>",
        "linkUrl": "<string>",
        "mediaUrls": [
          "<string>"
        ],
        "objectStoryId": "<string>",
        "objectType": "<string>",
        "pageId": "<string>",
        "pinterestDescription": "<string>",
        "pinterestImageUrl": "<string>",
        "pinterestTitle": "<string>",
        "servingHoldReasons": [
          "<string>"
        ],
        "thumbnailUrl": "<string>",
        "urlTags": "<string>",
        "videoId": "<string>",
        "videoUrl": "<string>",
        "whatsappPhoneNumber": "<string>",
        "youtubeVideoIds": [
          "<string>"
        ]
      },
      "creativeType": "carousel",
      "goal": "engagement",
      "isExternal": true,
      "metrics": {
        "actionValues": {},
        "actions": {},
        "allConversions": 123,
        "clicks": 123,
        "conversions": 123,
        "costPerAction": {},
        "costPerConversion": 123,
        "costPerThruplay": 123,
        "cpc": 123,
        "cpm": 123,
        "ctr": 123,
        "engagement": 123,
        "engagementBreakdown": {},
        "funnel": {},
        "impressions": 123,
        "inlineLinkClickCtr": 123,
        "inlineLinkClicks": 123,
        "lastSyncedAt": "2023-11-07T05:31:56Z",
        "outboundClicks": 123,
        "outboundClicksCtr": 123,
        "purchaseValue": 123,
        "reach": 123,
        "roas": 123,
        "spend": 123,
        "uniqueClicks": 123,
        "uniqueCtr": 123,
        "video2SecWatchedActions": 123,
        "video30SecWatchedActions": 123,
        "video6SecFocusedViews": 123,
        "video6SecWatchedActions": 123,
        "videoAvgTimeWatchedActions": 123,
        "videoP100WatchedActions": 123,
        "videoP25WatchedActions": 123,
        "videoP50WatchedActions": 123,
        "videoP75WatchedActions": 123,
        "videoP95WatchedActions": 123,
        "videoPlayActions": 123,
        "videoThruplayWatchedActions": 123
      },
      "name": "<string>",
      "optimizationGoal": "<string>",
      "platform": "facebook",
      "platformAdAccountId": "<string>",
      "platformAdAccountName": "<string>",
      "platformAdId": "<string>",
      "platformAdSetId": "<string>",
      "platformCampaignId": "<string>",
      "platformCreatedAt": "2023-11-07T05:31:56Z",
      "platformObjective": "<string>",
      "promotedObject": {
        "application_id": "<string>",
        "custom_event_type": "<string>",
        "page_id": "<string>",
        "pixel_id": "<string>",
        "product_set_id": "<string>"
      },
      "rejectionReason": "<string>",
      "reviewStatus": "in_review",
      "roasAverageFloor": 123,
      "schedule": {
        "endDate": "2023-11-07T05:31:56Z",
        "startDate": "2023-11-07T05:31:56Z"
      },
      "servingStatuses": [
        "<string>"
      ],
      "status": "active",
      "synced": true,
      "targeting": {},
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "limit": 123,
    "page": 123,
    "pages": 123,
    "total": 123
  }
}

{
  "error": {
    "code": "<string>",
    "details": {},
    "message": "<string>",
    "param": "<string>",
    "retryHint": "<string>",
    "retryable": true,
    "type": "<string>"
  }
}

Request contract

Method and path: GET /apis/v1/ads
Availability: enabled
Request URL template: https://api.aisa.one/apis/v1/ads
connectionId: query; required
page: query; optional
limit: query; optional
source: query; optional
status: query; optional
platform: query; optional
adAccountId: query; optional
pageId: query; optional
campaignId: query; optional
adSetId: query; optional
platformAdId: query; optional
effectiveObjectStoryId: query; optional
effectiveInstagramMediaId: query; optional
fromDate: query; optional
toDate: query; optional
Runtime facts: fe60122939c67dc98a3a6ac6b97bd5c326b526105150c8959304dd2160d4dd09

Complete OpenAPI definition Effective request and pricing declaration (including authentication and referenced schemas):

{
  "operationId": "get_aisa_ads_apis_v1_ads",
  "method": "GET",
  "path": "/apis/v1/ads",
  "servers": [
    {
      "url": "https://api.aisa.one"
    }
  ],
  "parameters": [
    {
      "description": "The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.",
      "in": "query",
      "name": "connectionId",
      "required": true,
      "schema": {
        "pattern": "^adc_[0-9A-Za-z]+$",
        "type": "string"
      }
    },
    {
      "description": "Page number (1-based)",
      "in": "query",
      "name": "page",
      "required": false,
      "schema": {
        "default": 1,
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "required": false,
      "schema": {
        "default": 50,
        "maximum": 500,
        "minimum": 1,
        "type": "integer"
      }
    },
    {
      "in": "query",
      "name": "source",
      "required": false,
      "schema": {
        "default": "all",
        "enum": [
          "aisa",
          "all"
        ],
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "status",
      "required": false,
      "schema": {
        "enum": [
          "active",
          "paused",
          "pending_review",
          "rejected",
          "completed",
          "cancelled",
          "error"
        ],
        "type": "string"
      }
    },
    {
      "in": "query",
      "name": "platform",
      "required": false,
      "schema": {
        "enum": [
          "facebook",
          "instagram",
          "tiktok",
          "linkedin",
          "pinterest",
          "google",
          "twitter",
          "openai",
          "reddit",
          "microsoft",
          "meta",
          "x"
        ],
        "type": "string"
      }
    },
    {
      "description": "Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /apis/v1/ads/campaigns and /apis/v1/ads/tree.",
      "in": "query",
      "name": "adAccountId",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager).",
      "in": "query",
      "name": "pageId",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Platform campaign ID (filter ads within a campaign) Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
      "in": "query",
      "name": "campaignId",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
      "in": "query",
      "name": "adSetId",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Meta ad ID. Returns the ad with this platform-side ad ID. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.",
      "in": "query",
      "name": "platformAdId",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Facebook `{pageId}_{postId}` of the post the ad's engagement lives on (Meta `effective_object_story_id`).",
      "in": "query",
      "name": "effectiveObjectStoryId",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Instagram media ID of the boosted post (Meta `effective_instagram_media_id`).",
      "in": "query",
      "name": "effectiveInstagramMediaId",
      "required": false,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.",
      "in": "query",
      "name": "fromDate",
      "required": false,
      "schema": {
        "format": "date",
        "type": "string"
      }
    },
    {
      "description": "End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.",
      "in": "query",
      "name": "toDate",
      "required": false,
      "schema": {
        "format": "date",
        "type": "string"
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-aisa-status": "enabled",
  "x-aisa-pricing": {
    "description": "Ads operations are free. Ad spend is billed by the ad platform to the connected ad account, never by AIsa.",
    "kind": "no_customer_charge"
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}

Cost and request rules

A request reference price is not currently available; use a request quote where supported. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

connectionId

string

required

The ads connection (adc_...) the request runs on: one of yours, from GET /apis/v1/ads/connections. On a request with a JSON body it may be sent as a top-level body member instead.

Pattern: ^adc_[0-9A-Za-z]+$

page

integer

default:1

Page number (1-based)

Required range: x >= 1

limit

integer

default:50

Required range: 1 <= x <= 500

source

enum<string>

default:all

Available options:

aisa,

all

status

enum<string>

Available options:

active,

paused,

pending_review,

rejected,

completed,

cancelled,

error

platform

enum<string>

Available options:

facebook,

instagram,

tiktok,

linkedin,

pinterest,

google,

twitter,

openai,

reddit,

microsoft,

meta,

x

adAccountId

string

Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /apis/v1/ads/campaigns and /apis/v1/ads/tree.

pageId

string

Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager).

campaignId

string

Platform campaign ID (filter ads within a campaign) Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.

adSetId

string

Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.

platformAdId

string

Meta ad ID. Returns the ad with this platform-side ad ID. Must be yours: it is checked through the connection before the request is sent, and an id that is not yours answers not_found.

effectiveObjectStoryId

string

Facebook {pageId}_{postId} of the post the ad's engagement lives on (Meta effective_object_story_id).

effectiveInstagramMediaId

string

Instagram media ID of the boosted post (Meta effective_instagram_media_id).

fromDate

string<date>

Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.

toDate

string<date>

End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.

Response

Paginated ads

ads

object[]

Show child attributes

backfillPending

boolean

Meta only. Present and true while historical data is being backfilled.

pagination

object

Show child attributes

​Request contract

​Cost and request rules

Authorizations

Query Parameters

Response

Request contract

Cost and request rules