List creatives

GET

/v1/metrics/creatives

CURL *hnd = curl_easy_init();

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

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/creatives?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7"),
    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/creatives?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7"

  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/creatives?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7"))
    .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/creatives?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7")
  .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/creatives',
  params: {
    space_id: '6916bc3d-e1ab-425b-ac25-eefada01a9a2',
    ad_account_id: 'f0958ef1-b662-425b-8794-79ca648489c7'
  },
  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/creatives?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7';
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/creatives?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7")
  .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/creatives";

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

    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/creatives?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2&ad_account_id=f0958ef1-b662-425b-8794-79ca648489c7' \
  --header 'Authorization: Bearer <token>'

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

List the creatives run in the given ad accounts, most recently active first (never-active last). A creative is one piece of ad content, identified by a fingerprint of that content: the same video launched in several ads is one creative. Its id is the key of a group_by=creative insights row. List the ads running one with GET /v1/metrics/ads?creative_id=.

Different filters intersect: a row must match every filter given, and any one of the ids within each. Every ad_account_id must be visible in space_id — 404 otherwise, as on insights.

Pass fields to trim the response to the properties you actually need — e.g. ?fields=name,format 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.

ad_id

string

Only creatives run by these ads, comma-separated.

ad_campaign_id

string

Only creatives run by ads under these campaigns, comma-separated.

media_id

string

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

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 creative, instead of the full object. id is always included. Omit for the complete object. Selectable: id, name, thumbnail_url, format, duration_seconds, width, height, ad_account_ids, ad_count, media_ids, first_active_at, last_active_at.

Responses

200

application/json

object

data

required

Array<object>

object

required

The creative’s fingerprint — the same value GET /v1/metrics/insights (and query_metrics) returns as key under group_by=creative, and what creative_id takes on GET /v1/metrics/ads. Not a UUID.

string

name

required

The name of the earliest-launched ad running it (else the platform’s creative name) — the same name its group_by=creative insights row carries.

string

thumbnail_url

required

The earliest-launched ad’s thumbnail, or null when Focal has none.

string

nullable

format

required

video when the creative contains a video, image when it contains only images, null when the platform reported no media breakdown (e.g. dynamic creatives).

string

nullable

Allowed values: video image

duration_seconds

required

Length of the video, or null for a non-video creative.

number

nullable

width

required

Pixel width of its video (or image), when known.

number

nullable

height

required

Pixel height of its video (or image), when known.

number

nullable

ad_account_ids

required

The requested ad accounts it appears in.

Array<string>

ad_count

required

How many ads in those accounts run it. List them with GET /v1/metrics/ads?creative_id=.

number

media_ids

required

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

Array<string>

first_active_at

required

YYYY-MM-DD of the earliest first-active day across its ads, or null when none has run.

string format: date

nullable

last_active_at

required

YYYY-MM-DD of the latest active day across its ads, or null when none has run.

string format: date

nullable

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": "9f2a64e1b87d3350a1c4e7b20d58f6c3",
      "name": "Hero video – 4:5 cut",
      "thumbnail_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/489012345_120210987654321100_n.jpg",
      "format": "video",
      "duration_seconds": 15.2,
      "width": 1080,
      "height": 1350,
      "ad_account_ids": [
        "f0958ef1-b662-425b-8794-79ca648489c7"
      ],
      "ad_count": 3,
      "media_ids": [
        "786beeda-55ac-4025-bf6e-43b2918e84a9"
      ],
      "first_active_at": "2027-03-04",
      "last_active_at": "2027-03-28"
    }
  ],
  "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.