Get an ad

GET

/v1/metrics/ads/{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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291?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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291?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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291?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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291?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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291?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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291',
  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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291?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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291?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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291";

    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/ads/0c4a206c-ec59-4a8d-b882-e557d0fd5291?space_id=6916bc3d-e1ab-425b-ac25-eefada01a9a2'

Fetch a single ad — for example the key of a group_by=ad insights row.

Returns 404 when the ad doesn’t exist, belongs to another organization, or its ad account isn’t visible in space_id.

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

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

Example

0c4a206c-ec59-4a8d-b882-e557d0fd5291

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

Responses

200

application/json

object

data

required

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>

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

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.