Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.emergedata.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 TypeDescription
🔍 Search EventsSearch queries and results across platforms
🌐 Browsing EventsWebsites visited and page views
📺 YouTube EventsYouTube videos watched and interactions
📢 Ads EventsAdvertisements seen across the web
🧾 Receipts EventsPurchase 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"
}
FieldTypeDescription
dataarrayEvent records for the endpoint
countintegerNumber of records returned
next_cursorstring | nullCursor for next page
has_morebooleanWhether more records exist
applied_ingested_endISO 8601 | nullEffective ingestion cutoff used by server

​
Common event fields

Every event includes these standard fields:
Data Point NameExplanationExample Value
user_idYour unique identifier for this person"psub_d4e5f6789012345678901234abcdef01"
event_idUnique ID for this specific event (used to avoid duplicates)102938
timestampWhen this event happened"2026-02-10T08:22:11Z"
ingested_atWhen Emerge received this event"2026-02-10T08:23:40Z"
categoryThe 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 NameExplanationExample Value
urlThe web address where the search happened"https://www.google.com/search?q=running+shoes"
titleThe page title shown in the browser tab"running shoes - Google Search"
queryThe exact words the person searched for"running shoes"
intentWhy they searched: looking for info, ready to buy, or finding a specific site"transactional" (options: "informational", "transactional", "navigational")
categoryThe topic category this search relates to"/Shopping/Apparel/Footwear"
brandsBrand names found in the search results["Nike", "Adidas"]
{
  "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 NameExplanationExample Value
urlThe web address of the page visited"https://www.nike.com/running-shoes"
titleThe page title shown in the browser tab"Running Shoes - Nike.com"
page_categoryThe type of page visited (like product page, article, homepage)"product"
categoryThe topic category this page relates to"/Shopping/Apparel/Footwear"
brandsBrand names detected on the page["Nike"]
{
  "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 NameExplanationExample Value
urlThe YouTube video web address"https://www.youtube.com/watch?v=dQw4w9WgXcQ"
titleThe video title"Best Running Shoes for Beginners"
categoryThe topic category this video relates to"/Sports/Running"
brandsBrand names mentioned or shown in the video["Nike", "Adidas"]
{
  "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 NameExplanationExample Value
source_domainThe website where the ad was shown"cnn.com"
landing_domainThe website the ad links to"nike.com"
urlThe full web address the ad links to"https://www.nike.com/sale"
titleThe headline or text shown in the ad"Nike Sale - Up to 50% Off"
categoryThe topic category this ad relates to"/Shopping/Apparel/Footwear"
brandsBrand names associated with the ad["Nike"]
ad_networkThe company serving the ad (like Google, Meta)"Google Ads"
{
  "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 NameExplanationExample Value
subjectThe email subject line"Your Nike.com order confirmation"
retailer_nameThe store or website where the purchase was made"Nike.com"
receipt_currencyThe currency used for the purchase"USD"
total_valueThe total amount spent149.99
itemsList of items purchased (see item details below)[{...}, {...}]
brandsBrand names from all items in the receipt["Nike"]
Receipt item details: Each item in the items array includes:
Data Point NameExplanationExample Value
nameThe product name"Air Max 90"
quantityHow many of this item were purchased1
unit_priceThe price for one item149.99
brandThe brand of this specific item"Nike"
categoryThe product category"/Shopping/Apparel/Footwear"
{
  "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;
}