List metrics

GET

/v1/metrics/features

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/metrics/features?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/features?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/features?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/features?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/features?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/features',
  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/features?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/features?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/features";

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

The metric keys GET /v1/metrics/insights accepts for these ad accounts, including each account’s own synced conversion metrics. Check queryable before using a key — the catalog also carries properties (launch date, ad name) that can’t be aggregated. disabled keys are hidden in the Focal UI and remain queryable here. An account-synced key carries no type metadata: its data_type and aggregation are null.

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 whose metric catalog to return, comma-separated.

Responses

200

application/json

object

data

required

Array<object>

object

key

required

The key to pass as a metric.

string

name

required

string

detail

required

string

nullable

data_type

required

null for an account-synced key, which carries no type metadata.

string

nullable

aggregation

required

string

nullable

queryable

required

Whether this key can be aggregated by the insights endpoint. false for properties (launch date, ad name).

boolean

core

required

boolean

disabled

required

Hidden in the Focal UI. Still queryable — the flag is a display preference, not a permission.

boolean

formula

required

Set when the key is a ratio (formula.<numerator>.<denominator>); formula.spend.<key> is cost-per-.

object

numerator

required

string

denominator

required

string

Example

{
  "data": [
    {
      "key": "formula.clicks.impressions",
      "name": "CTR",
      "detail": "The click through rate",
      "data_type": "number",
      "aggregation": "average",
      "queryable": true,
      "core": true,
      "disabled": false,
      "formula": {
        "numerator": "clicks",
        "denominator": "impressions"
      }
    }
  ]
}

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.