List ads

GET

/v1/metrics/ads

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet"),
    Headers =
    {
        { "Authorization", "Bearer <token>" },
    },
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

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

func main() {

  url := "https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet"

  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(res)
  fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet"))
    .header("Authorization", "Bearer <token>")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.focal.inc/v1/metrics/ads',
  params: {
    space_id: '6916bc3d-e1ab-425b-ac25-eefada01a9a2',
    ad_account_id: 'f0958ef1-b662-425b-8794-79ca648489c7',
    status: 'not_launched_yet'
  },
  headers: {Authorization: 'Bearer <token>'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.focal.inc/v1/metrics/ads";

    let querystring = [
        ("space_id", "6916bc3d-e1ab-425b-ac25-eefada01a9a2"),
        ("ad_account_id", "f0958ef1-b662-425b-8794-79ca648489c7"),
        ("status", "not_launched_yet"),
    ];

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.get(url)
        .query(&querystring)
        .headers(headers)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request GET \
  --url 'https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet' \
  --header 'Authorization: Bearer <token>'

wget --quiet \
  --method GET \
  --header 'Authorization: Bearer <token>' \
  --output-document \
  - 'https://api.focal.inc/v1/metrics/ads?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7&status=not_launched_yet'

List the ads in the given ad accounts, with the campaign and ad set each runs under, the creatives it runs, and the library media it resolves to. An ad’s id is the key of a group_by=ad insights row.

Ordered by last_active_at descending (never-active rows last), then by name. query matches names case-insensitively; status narrows to one delivery status. Every ad_account_id must be visible in space_id — 404 otherwise, as on insights.

Different filters intersect: a row must match every filter given, and any one of the ids within each. (Insights filters combine the other way — as one OR set.)

Pass fields to trim the response to the properties you actually need — e.g. ?fields=name,status returns just those (plus id, always). Unknown names are rejected rather than ignored.

Required scope: metrics:read — a scope of its own, deliberately not covered by media:read, because ad spend and revenue are a different sensitivity class from asset metadata. (all:read does cover it.)

space_id is required and decides what you can see. The caller must be able to read that space (404 otherwise, so a space you can’t reach is indistinguishable from one that doesn’t exist), and an ad account is returned only when it is shared with that space or with the whole organization — or is private and was connected by the calling user. Rate-limit cost: 5.

Authorizations

bearerAuth

Parameters

Query Parameters

space_id

required

string format: uuid

Example

6916bc3d-e1ab-425b-ac25-eefada01a9a2

Required. The single space to query, as a UUID. The API reads one space at a time — comma-separated lists and wildcards are not accepted, and there is no implicit default.

ad_account_id

required

string

Example

f0958ef1-b662-425b-8794-79ca648489c7

Ad accounts to read from, comma-separated — ids from GET /v1/metrics/ad-accounts. Each must be visible in space_id.

query

string

Only return rows whose name contains this (case-insensitive).

status

string

Allowed values: not_launched_yet live paused

Only return rows with this delivery status.

limit

integer

>= 1 <= 100

Max rows per page (1–100). Default 25.

cursor

string

Pagination cursor returned as next_cursor from the previous page.

fields

string

Return only these properties of each ad, instead of the full object. id is always included. Omit for the complete object. Selectable: id, external_id, ad_account_id, name, status, first_active_at, last_active_at, created_at, updated_at, ad_set_id, ad_campaign_id, thumbnail_url, preview_url, creative_ids, media_ids.

ad_campaign_id

string

Only ads under these campaigns, comma-separated.

ad_set_id

string

Only ads in these ad sets, comma-separated.

creative_id

string

Only ads running these creatives (ids from GET /v1/metrics/creatives), comma-separated.

media_id

string

Only ads linked to these media assets in space_id, comma-separated.

Responses

200

application/json

object

data

required

Array<object>

object

required

Focal’s id for the ad — the key of a group_by=ad insights row, and what ad_id takes on GET /v1/metrics/insights (filters.ad_ids in query_metrics) and /v1/metrics/creatives.

string format: uuid

external_id

required

The id on the ad platform itself. Use it to correlate with data pulled straight from the platform; use id when calling Focal.

string

ad_account_id

required

The ad account it belongs to — an id from GET /v1/metrics/ad-accounts.

string format: uuid

name

required

The name as it appears on the ad platform.

string

status

required

Delivery status as last synced from the ad platform.

string

Allowed values: not_launched_yet live paused

first_active_at

required

YYYY-MM-DD of the first day the platform reported activity, or null when it never ran.

string format: date

nullable

last_active_at

required

YYYY-MM-DD of the most recent day the platform reported activity, or null when it never ran.

string format: date

nullable

created_at

required

When Focal first synced it.

string format: date-time

updated_at

required

string format: date-time

ad_set_id

required

The ad set it runs in (an id from GET /v1/metrics/ad-sets), or null when Focal hasn’t synced one.

string format: uuid

nullable

ad_campaign_id

required

The campaign it runs under (an id from GET /v1/metrics/ad-campaigns), or null when Focal hasn’t synced one.

string format: uuid

nullable

thumbnail_url

required

The ad platform’s thumbnail for the ad. Platform-hosted and may expire.

string

nullable

preview_url

required

The ad platform’s preview link for the ad, when it has one.

string

nullable

creative_ids

required

The creatives the ad runs — ids for GET /v1/metrics/creatives. Empty until Focal has fingerprinted its content.

Array<string>

media_ids

required

The media assets in space_id that the ad resolves to — pass to GET /v1/media. Media outside the space are never listed.

Array<string>

next_cursor

required

Pass back as cursor to fetch the next page. null on the last page.

string

nullable

has_more

required

true when another page is available. Equivalent to next_cursor !== null.

boolean

Example

{
  "data": [
    {
      "id": "0c4a206c-ec59-4a8d-b882-e557d0fd5291",
      "external_id": "120210987654321100",
      "ad_account_id": "f0958ef1-b662-425b-8794-79ca648489c7",
      "name": "Hero video – 4:5 cut",
      "status": "not_launched_yet",
      "first_active_at": "2027-03-04",
      "last_active_at": "2027-03-28",
      "created_at": "2027-03-04T10:15:00Z",
      "updated_at": "2027-03-06T14:42:00Z",
      "ad_set_id": "43da78f6-914b-4e92-8e58-96a42791ac4c",
      "ad_campaign_id": "7c3b0b7e-980f-4ac8-8fce-2fe0084d9231",
      "thumbnail_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/489012345_120210987654321100_n.jpg",
      "preview_url": "https://www.facebook.com/ads/archive/render_ad/?id=120210987654321100",
      "creative_ids": [
        "9f2a64e1b87d3350a1c4e7b20d58f6c3"
      ],
      "media_ids": [
        "786beeda-55ac-4025-bf6e-43b2918e84a9"
      ]
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNy0wMy0wNFQxMDoxNTowMC4wMDBaIiwiaSI6Ijc4NmJlZWRhLTU1YWMtNDAyNS1iZjZlLTQzYjI5MThlODRhOSJ9",
  "has_more": true
}

400

The request was malformed (invalid cursor, unknown type, validation failure, etc.). error.code is bad_request.

application/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body",
    "details": [
      {
        "field": "space_id",
        "issue": "Invalid UUID"
      }
    ]
  }
}

401

Missing, invalid, or disabled token. error.code is unauthenticated.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "unauthenticated",
    "message": "Bearer token is missing or invalid"
  }
}

403

The token doesn’t have the scope this endpoint requires. error.code is forbidden.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "forbidden",
    "message": "Token doesn't have the required scope"
  }
}

404

Resource doesn’t exist or is outside the token’s space allow-list. The two cases share a response shape so a restricted token can’t probe for the existence of out-of-scope spaces. error.code is not_found.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}

429

Rate limit exceeded. error.code is rate_limited. Wait the number of seconds in the Retry-After header before retrying. Quotas are per-token; see the “Rate limiting” section at the top of this document.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 1000 units per 60s exceeded (this request cost 5)"
  }
}

Headers

Retry-After

integer

Example

Seconds to wait before retrying.