Intent & Signals

graph8’s intent surface is two layers:

1. /api/v1/intent/* — full account-level intent tracking. Keyword groups, page visitor records, contact-level engagement, account-level intent search.
2. /api/v1/public/signals/company — a single endpoint that returns an aggregate intent score for one domain. Write-key safe (works from browser code).

Use the public endpoint for quick lookups in a browser; use the server-side intent surface for prospecting / SDR workflows.

Tip

Most read endpoints are free. Intent signal processing (when a new visitor record arrives) consumes 1 credit per signal — that happens automatically when tracking events flow in; you don’t trigger it from these endpoints.

Auth

Every call needs Authorization: Bearer $G8_API_KEY. The X-Org-Id is bound to the key automatically. Get a key in 30 seconds →

30-second start

Get org-level intent stats:

cURL

curl 'https://be.graph8.com/api/v1/intent/stats' \
  -H "Authorization: Bearer $G8_API_KEY"

TypeScript

import { g8 } from '@graph8/sdk';
g8.init({ apiKey: process.env.G8_API_KEY! });

const { data } = await g8.intent.stats();
// → { total_keywords, total_pages, total_visitors_30d, total_companies_30d }

CLI

g8 intent-stats

MCP

Ask your agent: “What’s our intent stats?” → tool: g8_intent_stats.

Quick reference

Endpoint	Method	Purpose
/intent/stats	GET	Org-level totals (last 30 days)
/intent/keywords/list	POST	List tracked keywords (paginated)
/intent/keywords/create-from-domain	POST	Track every page on a domain
/intent/keywords/{id}	DELETE	Stop tracking
/intent/keywords/{id}/companies	POST	Companies interested in a keyword
/intent/keywords/{id}/contacts	POST	Contacts interested in a keyword
/intent/keywords/{id}/urls	POST	URLs associated with a keyword
/intent/pages-by-domain	POST	Tracked pages on a domain
/intent/pages/search	POST	Search pages by URL or keyword
/intent/pages/visitors	POST	Visitors for a single page URL
/intent/pages/contacts	POST	Contacts who visited a page
/intent/pages/visitor-counts	POST	Aggregate counts for multiple URLs
/intent-search/url-companies (no /api/v1 prefix)	POST	Companies whose users visited a URL
/public/signals/company	GET	Aggregate intent score for one domain (write-key safe)

Org-level stats

GET /api/v1/intent/stats

{
  "data": {
    "total_keywords": 42,
    "total_pages": 318,
    "total_visitors_30d": 12500,
    "total_companies_30d": 1240
  }
}

Keyword tracking

Create a keyword group from a domain

POST /api/v1/intent/keywords/create-from-domain
Content-Type: application/json

{ "domain": "competitor.com" }

graph8 auto-tracks every public page on the domain. The system periodically re-discovers new pages.

List + delete

POST /api/v1/intent/keywords/list
{ "page": 1, "limit": 25, "search": "pricing" }

DELETE /api/v1/intent/keywords/{keyword_id}

Deleting a keyword stops new tracking. Historical visitor records are retained — they just don’t roll up to the deleted keyword anymore.

Per-keyword data

POST /api/v1/intent/keywords/{keyword_id}/companies
{ "limit": 50, "date_from": "2026-05-01" }

POST /api/v1/intent/keywords/{keyword_id}/contacts
{ "limit": 50 }

POST /api/v1/intent/keywords/{keyword_id}/urls
{ "limit": 50 }

Each returns data keyed appropriately (companies, contacts, pages).

Page-level data

POST /api/v1/intent/pages-by-domain
{ "domain": "example.com", "limit": 50 }

POST /api/v1/intent/pages/search
{ "query": "pricing", "limit": 25 }

POST /api/v1/intent/pages/visitors
{ "url": "https://example.com/pricing", "limit": 50, "date_from": "2026-05-01" }

POST /api/v1/intent/pages/contacts
{ "url": "https://example.com/pricing", "limit": 50 }

POST /api/v1/intent/pages/visitor-counts
{ "urls": ["https://example.com/pricing", "https://example.com/docs"] }

Visitor records include the IP-resolved company, page-view count, first / last seen timestamps.

Account-level intent search

Different mount point

The intent-search surface is mounted at the bare host (no /api/v1 prefix), unlike the rest of the developer API. Send the full URL exactly as shown.

POST https://be.graph8.com/intent-search/url-companies
Authorization: Bearer $G8_API_KEY
Content-Type: application/json

{ "url": "https://competitor.com/pricing", "date_from": "2026-04-01", "limit": 50 }

Returns companies whose tracked users visited the URL. Useful for “show me everyone shopping our competitor right now” workflows.

Public signal endpoint (write-key safe)

GET /api/v1/public/signals/company?domain=acme.com
Authorization: Bearer pk_<write_key>

Returns an aggregate score { domain, intent: "low|medium|high", score: 0-100, signals: [...] }. Safe to call from browser code with a write key — handy for “is this signed-up user a hot account?” checks.

Credit costs

Operation	Credits
Read endpoints (keywords, pages, visitors, stats)	Free
Public signal endpoint	Free
Intent signal processing (background, per inbound event)	1 credit per 10 events
Keyword creation / deletion	Free

The 1-per-10-events rate is part of the platform-level event-stream pricing — see Pricing.

Errors

Status	Cause	Fix
401	Missing or invalid Authorization: Bearer header	Get a key
402	Out of credits (waterfall enrichment, AI generation, voice minutes)	Top up in Settings → Billing, or switch to Platform
404	Resource ID doesn’t exist	List first to verify the ID
422	Validation error in request body	Inspect error.message + error.field in the response
429	Rate limit (5 rps per org)	Backoff per Retry-After header. See Rate Limits
5xx	graph8 error	Retry with exponential backoff (5s → 30s → 120s)

The full error envelope shape: { "error": { "code": "...", "message": "...", "field": "...", "request_id": "..." } }. Include the request_id in any support ticket. See Errors for the canonical reference.

See also

• SDK intent methods — same surface in TypeScript
• CLI intent commands
• MCP intent tools
• Public Endpoints — full write-key-safe surface
• Pricing — full credit matrix