Data Schema

Use this page as the canonical schema reference for Query API payloads.

Event Types Overview

The Query API provides five types of enriched events:

Event Type	Description
🔍 Search Events	Search queries and results across platforms
🌐 Browsing Events	Websites visited and page views
📺 YouTube Events	YouTube videos watched and interactions
📢 Ads Events	Advertisements seen across the web
🧾 Receipts Events	Purchase receipts and transaction data

Sync response envelope

All sync endpoints return:

{
  "data": [],
  "count": 0,
  "next_cursor": null,
  "has_more": false,
  "applied_ingested_end": "2026-02-12T09:10:11Z"
}

Field	Type	Description
`data`	array	Event records for the endpoint
`count`	integer	Number of records returned
`next_cursor`	string \| null	Cursor for next page
`has_more`	boolean	Whether more records exist
`applied_ingested_end`	ISO 8601 \| null	Effective ingestion cutoff used by server

Common event fields

Every event includes these standard fields:

Data Point Name	Explanation	Example Value
`user_id`	Your unique identifier for this person	`"psub_d4e5f6789012345678901234abcdef01"`
`event_id`	Unique ID for this specific event (used to avoid duplicates)	`102938`
`timestamp`	When this event happened	`"2026-02-10T08:22:11Z"`
`ingested_at`	When Emerge received this event	`"2026-02-10T08:23:40Z"`
`category`	The topic category (from Google Topics taxonomy)	`"/Shopping/Apparel/Footwear"`

Event type schemas

Search Events

Captures what people search for online. Endpoint: /v1/sync/get_search

Data Point Name	Explanation	Example Value
`url`	The web address where the search happened	`"https://www.google.com/search?q=running+shoes"`
`title`	The page title shown in the browser tab	`"running shoes - Google Search"`
`query`	The exact words the person searched for	`"running shoes"`
`intent`	Why they searched: looking for info, ready to buy, or finding a specific site	`"transactional"` (options: `"informational"`, `"transactional"`, `"navigational"`)
`category`	The topic category this search relates to	`"/Shopping/Apparel/Footwear"`
`brands`	Brand names found in the search results	`["Nike", "Adidas"]`

Response example

{
  "data": [
    {
      "user_id": "psub_d4e5f6789012345678901234abcdef01",
      "event_id": 102938,
      "timestamp": "2026-02-10T08:22:11Z",
      "ingested_at": "2026-02-10T08:23:40Z",
      "url": "https://www.google.com/search?q=running+shoes",
      "title": "running shoes - Google Search",
      "query": "running shoes",
      "intent": "transactional",
      "category": "/Shopping/Apparel/Footwear",
      "brands": ["Nike"]
    }
  ],
  "count": 1,
  "next_cursor": null,
  "has_more": false,
  "applied_ingested_end": "2026-02-12T09:10:11Z"
}

Browsing Events

Captures websites people visit. Endpoint: /v1/sync/get_browsing

Data Point Name	Explanation	Example Value
`url`	The web address of the page visited	`"https://www.nike.com/running-shoes"`
`title`	The page title shown in the browser tab	`"Running Shoes - Nike.com"`
`page_category`	The type of page visited (like product page, article, homepage)	`"product"`
`category`	The topic category this page relates to	`"/Shopping/Apparel/Footwear"`
`brands`	Brand names detected on the page	`["Nike"]`

Response example

{
  "data": [
    {
      "user_id": "psub_d4e5f6789012345678901234abcdef01",
      "event_id": 102940,
      "timestamp": "2026-02-10T09:15:22Z",
      "ingested_at": "2026-02-10T09:16:33Z",
      "url": "https://www.nike.com/running-shoes",
      "title": "Running Shoes - Nike.com",
      "page_category": "product",
      "category": "/Shopping/Apparel/Footwear",
      "brands": ["Nike"]
    }
  ],
  "count": 1,
  "next_cursor": null,
  "has_more": false,
  "applied_ingested_end": "2026-02-12T09:10:11Z"
}

YouTube Events

Captures YouTube videos people watch. Endpoint: /v1/sync/get_youtube

Data Point Name	Explanation	Example Value
`url`	The YouTube video web address	`"https://www.youtube.com/watch?v=dQw4w9WgXcQ"`
`title`	The video title	`"Best Running Shoes for Beginners"`
`category`	The topic category this video relates to	`"/Sports/Running"`
`brands`	Brand names mentioned or shown in the video	`["Nike", "Adidas"]`

Response example

{
  "data": [
    {
      "user_id": "psub_d4e5f6789012345678901234abcdef01",
      "event_id": 102942,
      "timestamp": "2026-02-10T10:30:45Z",
      "ingested_at": "2026-02-10T10:31:12Z",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "title": "Best Running Shoes for Beginners",
      "category": "/Sports/Running",
      "brands": ["Nike", "Adidas"]
    }
  ],
  "count": 1,
  "next_cursor": null,
  "has_more": false,
  "applied_ingested_end": "2026-02-12T09:10:11Z"
}

Ads Events

Captures online ads people see and click. Endpoint: /v1/sync/get_ads

Data Point Name	Explanation	Example Value
`source_domain`	The website where the ad was shown	`"cnn.com"`
`landing_domain`	The website the ad links to	`"nike.com"`
`url`	The full web address the ad links to	`"https://www.nike.com/sale"`
`title`	The headline or text shown in the ad	`"Nike Sale - Up to 50% Off"`
`category`	The topic category this ad relates to	`"/Shopping/Apparel/Footwear"`
`brands`	Brand names associated with the ad	`["Nike"]`
`ad_network`	The company serving the ad (like Google, Meta)	`"Google Ads"`

Response example

{
  "data": [
    {
      "user_id": "psub_d4e5f6789012345678901234abcdef01",
      "event_id": 102945,
      "timestamp": "2026-02-10T11:22:33Z",
      "ingested_at": "2026-02-10T11:23:01Z",
      "source_domain": "cnn.com",
      "landing_domain": "nike.com",
      "url": "https://www.nike.com/sale",
      "title": "Nike Sale - Up to 50% Off",
      "category": "/Shopping/Apparel/Footwear",
      "brands": ["Nike"],
      "ad_network": "Google Ads"
    }
  ],
  "count": 1,
  "next_cursor": null,
  "has_more": false,
  "applied_ingested_end": "2026-02-12T09:10:11Z"
}

Receipts Events

Captures purchases from email receipts. Endpoint: /v1/sync/get_receipts

Data Point Name	Explanation	Example Value
`subject`	The email subject line	`"Your Nike.com order confirmation"`
`retailer_name`	The store or website where the purchase was made	`"Nike.com"`
`receipt_currency`	The currency used for the purchase	`"USD"`
`total_value`	The total amount spent	`149.99`
`items`	List of items purchased (see item details below)	`[{...}, {...}]`
`brands`	Brand names from all items in the receipt	`["Nike"]`

Receipt item details: Each item in the items array includes:

Data Point Name	Explanation	Example Value
`name`	The product name	`"Air Max 90"`
`quantity`	How many of this item were purchased	`1`
`unit_price`	The price for one item	`149.99`
`brand`	The brand of this specific item	`"Nike"`
`category`	The product category	`"/Shopping/Apparel/Footwear"`

Response example

{
  "data": [
    {
      "user_id": "psub_d4e5f6789012345678901234abcdef01",
      "event_id": 102950,
      "timestamp": "2026-02-10T14:45:22Z",
      "ingested_at": "2026-02-10T14:46:11Z",
      "subject": "Your Nike.com order confirmation",
      "retailer_name": "Nike.com",
      "receipt_currency": "USD",
      "total_value": 149.99,
      "items": [
        {
          "name": "Air Max 90",
          "quantity": 1,
          "unit_price": 149.99,
          "brand": "Nike",
          "category": "/Shopping/Apparel/Footwear"
        }
      ],
      "brands": ["Nike"]
    }
  ],
  "count": 1,
  "next_cursor": null,
  "has_more": false,
  "applied_ingested_end": "2026-02-12T09:10:11Z"
}

Type-safe parsing examples

type SyncEnvelope<T> = {
  data: T[];
  count: number;
  next_cursor: string | null;
  has_more: boolean;
  applied_ingested_end: string | null;
};

type SearchEvent = {
  user_id: string;
  event_id: number;
  timestamp: string;
  ingested_at: string;
  url: string | null;
  title: string | null;
  query: string | null;
  intent: string | null;
  category: string | null;
  brands: string[];
};

async function fetchSearch(uid: string): Promise<SyncEnvelope<SearchEvent>> {
  const response = await fetch(
    `https://query.emergedata.ai/v1/sync/get_search?uid=${encodeURIComponent(uid)}`,
    { headers: { Authorization: `Bearer ${process.env.EMERGE_API_TOKEN ?? ''}` } }
  );

  if (!response.ok) {
    throw new Error(`Search request failed (${response.status})`);
  }

  const payload = (await response.json()) as SyncEnvelope<SearchEvent>;
  return payload;
}

from typing import Any, TypedDict
import os
import requests

class SearchEvent(TypedDict):
    user_id: str
    event_id: int
    timestamp: str
    ingested_at: str
    url: str | None
    title: str | None
    query: str | None
    intent: str | None
    category: str | None
    brands: list[str]

def fetch_search(uid: str) -> dict[str, Any]:
    response = requests.get(
        "https://query.emergedata.ai/v1/sync/get_search",
        params={"uid": uid},
        headers={"Authorization": f"Bearer {os.environ['EMERGE_API_TOKEN']}"},
        timeout=30
    )
    response.raise_for_status()
    return response.json()

Guides

Async Endpoints

Sync Endpoints

Event Types Overview

Sync response envelope

Common event fields

Event type schemas

Search Events

Browsing Events

YouTube Events

Ads Events

Receipts Events

Type-safe parsing examples

​Event Types Overview

​Sync response envelope

​Common event fields

​Event type schemas

​Search Events

​Browsing Events

​YouTube Events

​Ads Events

​Receipts Events

​Type-safe parsing examples

​Related docs

Event Types Overview

Sync response envelope

Common event fields

Event type schemas

Search Events

Browsing Events

YouTube Events

Ads Events

Receipts Events

Type-safe parsing examples

Related docs