Get a creative

GET

/v1/metrics/creatives/{id}

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/9f2a64e1b87d3350a1c4e7b20d58f6c3?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2");

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/9f2a64e1b87d3350a1c4e7b20d58f6c3?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2"),
    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/9f2a64e1b87d3350a1c4e7b20d58f6c3?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2"

  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/9f2a64e1b87d3350a1c4e7b20d58f6c3?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2"))
    .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/9f2a64e1b87d3350a1c4e7b20d58f6c3?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2")
  .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/9f2a64e1b87d3350a1c4e7b20d58f6c3',
  params: {space_id: '6916bc3d-e1ab-425b-ac25-eefada01a9a2'},
  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/9f2a64e1b87d3350a1c4e7b20d58f6c3?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2';
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/9f2a64e1b87d3350a1c4e7b20d58f6c3?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2")
  .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/9f2a64e1b87d3350a1c4e7b20d58f6c3";

    let querystring = [
        ("space_id", "6916bc3d-e1ab-425b-ac25-eefada01a9a2"),
    ];

    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);
}

wget --quiet \
  --method GET \
  --header 'Authorization: Bearer <token>' \
  --output-document \
  - 'https://api.focal.inc/v1/metrics/creatives/9f2a64e1b87d3350a1c4e7b20d58f6c3?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2'

Fetch a single creative by fingerprint — for example the key of a group_by=creative insights row. Aggregates over every ad account visible in space_id that runs it.

Returns 404 when no visible ad account runs it.

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: 1.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

>= 1 characters

Example

9f2a64e1b87d3350a1c4e7b20d58f6c3

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.

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

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

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"
  }
}

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.