Publish to learn

Read per-post metrics

GET /v1/projects/:projectId/metrics is the unified organic metrics endpoint. Scope by platform_post for a single post, social_account for one handle, or project for the whole customer — and the URL-level :projectId guards that the scoped entity belongs to your org.

curl "https://api.layers.com/v1/projects/$PROJECT_ID/metrics?scope=project&id=$PROJECT_ID&metrics=views&metrics=engagement_rate&metrics=watch_time_ms&since=2026-04-10T00:00:00Z&until=2026-04-17T00:00:00Z&granularity=day" \
  -H "Authorization: Bearer $LAYERS_API_KEY"

const params = new URLSearchParams({
  scope: "project",
  id: projectId,
  since: "2026-04-10T00:00:00Z",
  until: "2026-04-17T00:00:00Z",
  granularity: "day",
});
for (const m of ["views", "engagement_rate", "watch_time_ms"]) {
  params.append("metrics", m);
}

const res = await fetch(
  `https://api.layers.com/v1/projects/${projectId}/metrics?${params}`,
  { headers: { Authorization: `Bearer ${process.env.LAYERS_API_KEY}` } },
);
const { series, totals } = await res.json();

import os
import requests

res = requests.get(
    f"https://api.layers.com/v1/projects/{project_id}/metrics",
    headers={"Authorization": f"Bearer {os.environ['LAYERS_API_KEY']}"},
    params=[
        ("scope", "project"),
        ("id", project_id),
        ("since", "2026-04-10T00:00:00Z"),
        ("until", "2026-04-17T00:00:00Z"),
        ("granularity", "day"),
        ("metrics", "views"),
        ("metrics", "engagement_rate"),
        ("metrics", "watch_time_ms"),
    ],
)
body = res.json()
series, totals = body["series"], body["totals"]

{
  "scope": "project",
  "id": "prj_01HX9Y7K8M2P4RSTUV56789AB",
  "window": {
    "since": "2026-04-10T00:00:00Z",
    "until": "2026-04-17T00:00:00Z",
    "granularity": "day"
  },
  "series": [
    { "bucket": "2026-04-10", "views": 3120, "engagement_rate": 0.038, "watch_time_ms": 58120000 },
    { "bucket": "2026-04-11", "views": 5402, "engagement_rate": 0.044, "watch_time_ms": 102400000 }
  ],
  "totals": {
    "views": 48210,
    "engagement_rate": 0.041,
    "watch_time_ms": 892100000,
    "post_count": 23
  }
}

since and until are ISO-8601 datetimes — date-only strings like 2026-04-10 return VALIDATION. series[].bucket is the bucket start (date string at day/week granularity, full timestamp at hour). totals.post_count is always included so UIs can show "N posts" alongside the aggregates.

For paid metrics (spend, CPA, ROAS), call GET /v1/projects/:projectId/ads-metrics instead. Asking for conversions/spend/roas on this endpoint returns VALIDATION.

Find top performers

GET /v1/projects/:projectId/top-performers is the ranking endpoint. It cross-references organic post performance with any ads spend against those creatives and returns a single sorted list. You pick the axis with metric and the lookback with window.

curl "https://api.layers.com/v1/projects/$PROJECT_ID/top-performers?metric=engagement_rate&window=30d&sourceType=platform_post&limit=5" \
  -H "Authorization: Bearer $LAYERS_API_KEY"

{
  "metric": "engagement_rate",
  "window": "30d",
  "items": [
    {
      "rank": 1,
      "sourceType": "platform_post",
      "sourceId": null,
      "platformPostId": "pp_01H9ZXT7...",
      "adsContentId": "adc_01H9ZXT...",
      "title": "Get things done. Faster than your to-do list app did yesterday.",
      "thumbnailUrl": "https://media.meetsift.com/videos/ig_.../cover.jpg",
      "metricValue": 0.082,
      "organic": {
        "views": 14820,
        "engagementRate": 0.082,
        "watchTimeMs": 61400000,
        "platforms": ["tiktok"]
      },
      "paid": null
    }
  ]
}

metric options: views, engagement_rate, conversions, roas, watch_time_ms. Pick the one the customer's stage actually cares about — early-stage apps should look at engagement_rate and watch_time_ms because absolute views rewards luck; later-stage accounts should lean on conversions and roas.

window is 7d, 30d (default), or 90d. There is no offset or custom range — use /metrics for that.

sourceType[] restricts to content_container (Layers-generated), platform_post (UGC / organic posts), or manual. platform[] restricts organic rows by platform and has no effect on paid-only rows.

Every row carries both organic and paid blocks (either may be null). metricValue mirrors the value the ranker used so your UI can render "0.082" or "5.2x" without peeking into the subtree.

Commission more content from the winner

Two choices. If you want a close variant — same hook, same influencer, fresh execution — clone the post. If you want to try a new angle on the same theme, generate a new piece with the winner's hook pinned in the brief.

Option A: Clone the top performer

Clone-from-post is a target-first shape: you mint a fresh UUID for the new container client-side, PUT-style, and the :containerId in the URL carries that id. Replay with the same id and you get the same container back — the path itself is your idempotency key.

NEW_CONTAINER_ID=$(uuidgen)

curl -X POST "https://api.layers.com/v1/content/$NEW_CONTAINER_ID/clone-from-post" \
  -H "Authorization: Bearer $LAYERS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "'"$PROJECT_ID"'",
    "sourcePlatformPostId": "pp_01H9ZXT7...",
    "mode": "reimagine",
    "variations": 3
  }'

{
  "jobId": "job_01H9ZXV...",
  "kind": "content_clone_from_post",
  "status": "running",
  "containerId": "cnt_01H9ZXV...",
  "locationUrl": "/v1/jobs/job_01H9ZXV..."
}

A single job handles all variations. Poll it like any other content generation — see Jobs. See Clone a top performer for the difference between fork and reimagine.

Option B: Generate with the hook pinned

curl -X POST "https://api.layers.com/v1/projects/$PROJECT_ID/content" \
  -H "Authorization: Bearer $LAYERS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "video_remix",
    "variantCount": 2,
    "brief": {
      "hook": "Get things done. Faster than your to-do list app did yesterday.",
      "cta": "Download acme-todo",
      "targetPlatforms": ["tiktok", "instagram"],
      "themeTags": ["productivity", "speed"]
    }
  }'

Use this when the hook is landing but the execution feels stale. You get a new container with the winner's hook as a starting point but different visuals, captions, and editing.

Nudge the scoring pool when you need to

organic_score on ads_content rows decays over time. A post that was a top performer two weeks ago slides down the ranking as it ages, which makes room for fresh winners. Layers runs this for you on a 6-hour cadence.

If you need to force a creative into or out of the pool — say, a top performer you want to keep eligible past normal decay, or a post the customer asked you to stop promoting — use the override:

curl -X PATCH "https://api.layers.com/v1/projects/$PROJECT_ID/ads-content/adc_01H9ZXT..." \
  -H "Authorization: Bearer $LAYERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "override": "include" }'

override: "include" keeps the creative eligible regardless of score decay. "exclude" forces it ineligible. null clears the override and lets scoring run.

Use "include" sparingly. The scoring pool works because it's unopinionated about yesterday's winner — overriding too often turns off the learning.