Ad-click landings and conversions, aggregated

use Fetchski\AttractCmsLaravel\Facades\Attract;

$adsMetrics = Attract::adsMetrics()->getAdsMetrics();

{
  "from": "2026-09-01T00:00:00.000Z",
  "to": "2026-09-22T00:00:00.000Z",
  "groupBy": [
    "day",
    "platform"
  ],
  "landings": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "day": "2026-09-20",
          "platform": "google"
        },
        "landings": 41
      }
    ]
  },
  "conversions": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "currency": "USD",
          "day": "2026-09-20",
          "platform": "google-ads"
        },
        "conversions": 3,
        "retracted": 0,
        "value": 6400,
        "browserSent": 2,
        "serverSent": 3,
        "serverPending": 0,
        "serverFailed": 0,
        "serverSkipped": 0
      }
    ]
  }
}

use Fetchski\AttractCmsLaravel\Facades\Attract;

$adsMetrics = Attract::adsMetrics()->getAdsMetrics();

{
  "from": "2026-09-01T00:00:00.000Z",
  "to": "2026-09-22T00:00:00.000Z",
  "groupBy": [
    "day",
    "platform"
  ],
  "landings": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "day": "2026-09-20",
          "platform": "google"
        },
        "landings": 41
      }
    ]
  },
  "conversions": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "currency": "USD",
          "day": "2026-09-20",
          "platform": "google-ads"
        },
        "conversions": 3,
        "retracted": 0,
        "value": 6400,
        "browserSent": 2,
        "serverSent": 3,
        "serverPending": 0,
        "serverFailed": 0,
        "serverSkipped": 0
      }
    ]
  }
}

In your app

A controller answers a route on your app: it calls getAdsMetrics() and returns the answer.

Add the controller

app/Http/Controllers/GetAdsMetricsController.php

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Fetchski\AttractCmsLaravel\Data\AdsMetricsResponse;
use Fetchski\AttractCmsLaravel\Facades\Attract;

final class GetAdsMetricsController
{
    public function __invoke(): AdsMetricsResponse
    {
        return Attract::adsMetrics()->getAdsMetrics();
    }
}

Add the route

routes/web.php

use App\Http\Controllers\GetAdsMetricsController;
use Illuminate\Support\Facades\Route;

Route::get('/ads-metrics', GetAdsMetricsController::class);

Call it

Terminal

curl http://localhost:8000/ads-metrics

With php artisan serve running, it prints its answer as JSON.

To keep the call in an Action instead, this writes app/Actions/Attract/GetAdsMetrics.php (an invokable Action that calls getAdsMetrics()) and its test under tests/Feature/Actions/Attract/ (Pest when your app has it):

Terminal

php artisan make:attract-action adsMetrics.getAdsMetrics

Call it from the terminal

Terminal

php artisan attract:call adsMetrics.getAdsMetrics

It calls getAdsMetrics() on your default site and prints its answer as JSON. See Call any method from the terminal for every argument type. Two sections:

landings — page views whose URL carried an ad click ID, from the Request Log (every visitor counts; nothing identifying is used). Empty while the Request Log is switched off. Only day, platform (google, meta, tiktok, other), utmSource, utmCampaign and landingPath apply.
conversions — conversion events by when they happened. Always also grouped by currency. value sums restated values and leaves out retracted events. Grouped by platform (a destination such as google-ads), each row adds browser and server delivery outcomes — the delivery success rate.

Days are UTC. At most 5,000 rows per section.

Optional parameters

Named arguments, e.g. getAdsMetrics(from: …); leave out the optional ones.

\DateTimeInterface|string|null

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Start (inclusive), ISO 8601 date or time. Default: 30 days before to. Format: an ISO 8601 date and time.

\DateTimeInterface|string|null

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. End (exclusive), ISO 8601 date or time. Default: now. Format: an ISO 8601 date and time.

array<int, Enums\GroupBy|string>|Collection<int, Enums\GroupBy|string>|null

Optional. Leave it out (or pass null) and it isn’t sent: the site’s default applies. Comma-separated dimensions, or the parameter repeated. Each one of day, conversion, platform, utmSource, utmCampaign, landingPath. No duplicates.

Returns

An AdsMetricsResponse (Fetchski\AttractCmsLaravel\Data\AdsMetricsResponse). The aggregates. Read its properties ($adsMetrics->from): each says whether the site always sends it.

CarbonImmutable

Always sent. The window’s start (inclusive). Format: an ISO 8601 date and time.

CarbonImmutable

Always sent. The window’s end (exclusive). Format: an ISO 8601 date and time.

Collection<int, Enums\GroupBy|string>

Always sent. The dimensions asked for. Each one of day, conversion, platform, utmSource, utmCampaign, landingPath.

AdsMetricsResponseLandings

Always sent. An AdsMetricsResponseLandings. Page views whose URL carried an ad click ID (from the Request Log — empty while it is switched off). Grouped only by day, platform (google, meta, …), utmSource, utmCampaign and landingPath.

Show AdsMetricsResponseLandings (Fetchski\AttractCmsLaravel\Data\AdsMetricsResponseLandings)

Collection<int, string>|null

Sometimes sent: null when the site leaves it out. The dimensions applied here (the asked-for ones a page view has).

Collection<int, AdsMetricsResponseLandingsRowsItem>|null

Sometimes sent: null when the site leaves it out. A list of AdsMetricsResponseLandingsRowsItem. One per group, sorted by key (at most 5,000).

Show AdsMetricsResponseLandingsRowsItem (Fetchski\AttractCmsLaravel\Data\AdsMetricsResponseLandingsRowsItem)

AdsMetricsKey

Always sent. An AdsMetricsKey. The group this row totals; only the requested dimensions (and currency, for conversions) appear.

Show AdsMetricsKey (Fetchski\AttractCmsLaravel\Data\AdsMetricsKey)

?string

Sometimes sent: null when the site leaves it out. Conversions: the currency their value is in (rows never mix currencies); absent for events without one.

?CarbonImmutable

Sometimes sent: null when the site leaves it out. UTC day. Format: an ISO 8601 date (YYYY-MM-DD).

?string

Sometimes sent: null when the site leaves it out. Conversions: the Conversion’s id.

?string

Sometimes sent: null when the site leaves it out. Conversions: a destination (e.g. google-ads, meta); landings: the ad platform of the click id (google, meta, tiktok, other).

?string

Sometimes sent: null when the site leaves it out. The utm_source of the visit; absent when it had none.

?string

Sometimes sent: null when the site leaves it out. The utm_campaign of the visit; absent when it had none.

?string

Sometimes sent: null when the site leaves it out. The page the visit landed on (for a conversion: its last touch, else its first).

int

Always sent. Page views with an ad click id. At least 0.

AdsMetricsResponseConversions

Always sent. An AdsMetricsResponseConversions. Conversion events. value sums restated values and leaves out retracted events. Grouped by platform (a destination such as google-ads), each row adds delivery outcomes.

Show AdsMetricsResponseConversions (Fetchski\AttractCmsLaravel\Data\AdsMetricsResponseConversions)

Collection<int, string>|null

Sometimes sent: null when the site leaves it out. The dimensions applied here.

Collection<int, AdsMetricsResponseConversionsRowsItem>|null

Sometimes sent: null when the site leaves it out. A list of AdsMetricsResponseConversionsRowsItem. One per group (and currency), sorted by key (at most 5,000).

Show AdsMetricsResponseConversionsRowsItem (Fetchski\AttractCmsLaravel\Data\AdsMetricsResponseConversionsRowsItem)

AdsMetricsKey

Always sent. An AdsMetricsKey. The group this row totals; only the requested dimensions (and currency, for conversions) appear. Its fields are listed under the first AdsMetricsKey above.

int

Always sent. Events not retracted. At least 0.

int

Always sent. Events retracted. At least 0.

float

Always sent. Their value, restated values counted, retracted ones left out.

?int

Sometimes sent: null when the site leaves it out. Grouped by platform: events the page’s tag sent to it. At least 0.

?int

Sometimes sent: null when the site leaves it out. Grouped by platform: delivered by the server. At least 0.

?int

Sometimes sent: null when the site leaves it out. Grouped by platform: owed by the server (queued or retry). At least 0.

?int

Sometimes sent: null when the site leaves it out. Grouped by platform: server sends that failed. At least 0.

?int

Sometimes sent: null when the site leaves it out. not-configured, expired, not-sent or no-consent. At least 0.

Errors

Nothing to catch: the SDK retries what is safe, and Laravel logs and renders the rest (see Errors and testing).

400

The request is not valid. data.errors lists each problem with the path of the parameter or body field it concerns.Retried first: No. Read: errors() (field → messages), siteMessage().

401

The API key is missing, malformed, unknown, disabled, expired or archived (invalid), or a request that must be signed — by the route, or by the key’s own signing mode — has a missing, stale or wrong signature (an upload signs its SHA-256, declared in X-Fetchski-Content-SHA256, in the body’s place) (unauthorized).Retried first: No. Read: siteMessage(), errorName(), data().

403

The API key lacks the scope this route needs (the message names it), or the key is used from an address outside its allowlist.Retried first: No. Read: siteMessage(), errorName(), data().

404

Nothing with this identifier — or the caller may not use the Data API at all (anonymous visitors and non-admin sessions get 404 so the API is not advertised). A write while conversion tracking is switched off also answers 404.Retried first: No. Read: siteMessage(), errorName(), data().

429

The key used up its reads- or writes-per-minute limit (set per key; defaults 600 / 120). Still, after the client’s own waits and retries.Retried first: Yes: the client waits Retry-After (1 s when absent; over 60 s it gives up at once) and retries, up to retries times (2 by default). Read: retryAfter() (seconds, or null), siteMessage().

5xx

The site failed (or something in front of it did). Its logs say why.Retried first: A 502, 503 or 504: yes, after 0.5 s then 1 s. A 500: no. Read: siteMessage(), errorName(), data().

no answer

No answer: DNS, a refused connection, TLS, or the timeout (15 s per attempt by default).Retried first: Yes, after 0.5 s then 1 s. Read: reason(), neverConnected().

not sent

The client refused to send it (e.g. a path segment of ..); the site never saw it.Retried first: No. Read: reason() (what to change).

any other

Any other status, or a success whose JSON doesn’t match this SDK version’s types (update the SDK).Retried first: No. Read: reason(), status().

setup

Attract::site('acme') named a slug that isn’t under sites in config/fetchski-attract.php.Retried first: No: nothing was sent. Read: getMessage(), $e->slug.

setup

The site’s config entry is wrong: no url, a malformed api_key, a key filed under another slug, or no default site.Retried first: No: nothing was sent. Read: getMessage() (what to fix).

Behavior

Access: an API key with ads-metrics:read — or its group master ads:all, or admin:all — or a signed-in user holding the analytics:view permission. Anonymous callers get 404.
Rate limit: the key’s own reads-per-minute limit, set when the key is created (default 600); over it, 429 with Retry-After. The client waits and retries for you; you see RateLimited only if that runs out.
Retries: a read is safe to repeat: the client retries it on no answer, a 502/503/504 and a 429.
Timeout: 15 s per attempt by default; raise timeout in config/fetchski-attract.php for longer.

Test it

It calls the route above with the SDK faked: the fake answers every call with a valid example, so nothing leaves your machine and no config or key is needed. Save it as tests/Feature/GetAdsMetricsTest.php, then run your tests:

tests/Feature/GetAdsMetricsTest.php

<?php

declare(strict_types=1);

namespace Tests\Feature;

use Fetchski\AttractCmsLaravel\Facades\Attract;
use Tests\TestCase;

final class GetAdsMetricsTest extends TestCase
{
    public function test_get_ads_metrics(): void
    {
        Attract::fake();

        $this->getJson('/ads-metrics')->assertOk();

        Attract::assertCalled('adsMetrics.getAdsMetrics');
    }
}

Terminal

php artisan test

GET /ads-metrics

The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.

use Fetchski\AttractCmsLaravel\Facades\Attract;

$adsMetrics = Attract::adsMetrics()->getAdsMetrics();

{
  "from": "2026-09-01T00:00:00.000Z",
  "to": "2026-09-22T00:00:00.000Z",
  "groupBy": [
    "day",
    "platform"
  ],
  "landings": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "day": "2026-09-20",
          "platform": "google"
        },
        "landings": 41
      }
    ]
  },
  "conversions": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "currency": "USD",
          "day": "2026-09-20",
          "platform": "google-ads"
        },
        "conversions": 3,
        "retracted": 0,
        "value": 6400,
        "browserSent": 2,
        "serverSent": 3,
        "serverPending": 0,
        "serverFailed": 0,
        "serverSkipped": 0
      }
    ]
  }
}

Get started

Using the SDK

Going further

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Ad-click landings and conversions, aggregated

In your app

Call it from the terminal

Behavior

Test it

GET /ads-metrics

In your app

Call it from the terminal

Behavior

Test it

Related

GET /ads-metrics