Skip to main content

Your first request

This walkthrough takes you from nothing to a real result: authenticate, find the IDs you need, run a minimal analysis, and read the response.

Step 1 — Authenticate​

Log in and keep the session cookie (see Authentication):

POST /v1/auth/login
{ "meta": { "version": "v1" }, "data": { "email": "you@example.com", "password": "••••" } }

Step 2 — Find the IDs​

An analysis references a region, a sector and a brand by their identifiers. Discover them from the taxonomy catalogue:

  1. GET /v1/taxonomies/regions — pick a region code (e.g. us).
  2. GET /v1/taxonomies/regions/us/sectors — pick a sector_id.
  3. GET /v1/taxonomies/regions/us/sectors/{sector_id}/brands — pick a brand_id.

Step 3 — Run a minimal analysis​

Ask for one metric, one brand, over a short fixed period:

POST /v1/analyses/execute
{
  "meta": { "version": "v1" },
  "data": {
    "queries": [
      {
        "id": "first-query",
        "entity": { "region": "us", "sector_id": 1, "brand_id": 1007 },
        "period": {
          "start_date": { "date": "2024-01-01" },
          "end_date":   { "date": "2024-01-31" }
        },
        "metrics_score_types": { "buzz": "net_score" },
        "filters": []
      }
    ]
  }
}

Step 4 — Read the result​

The response contains one block per series. Each block's data is a cube indexed values[metric][date][perspective], where perspective includes the headline score and its components. See Output formats for the full shape.

What next​