@graph8/sdk 0.265.0 → 0.293.0

package/docs/api/snippet.d.ts

@@ -1,7 +1,7 @@
 /* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
 
 /**
- * Types for `g8.api.snippet` (Snippet): 2 operations.
+ * Types for `g8.api.snippet` (Snippet): 3 operations.
  *
  * For reading. In code, import from the package instead:
  *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
@@ -15,6 +15,7 @@
 export interface SnippetMembers {
   getFormTemplate: "get_form_template_snippet_form_get";
   getOrgSnippet: "get_org_snippet_snippet_get";
+  listOrgStreams: "list_org_streams_streams_get";
 }
 
 /** Input and output of every `g8.api.snippet` operation, keyed by operationId. */
@@ -26,6 +27,10 @@ export interface SnippetOperations {
    */
   get_form_template_snippet_form_get: {
     input: {
+    query?: {
+      /** Tracking stream whose write key the form uses (from GET /streams). Defaults as in GET /snippet. */
+      stream_id?: string | null;
+    };
     headers?: {
       "X-Target-Org-Id"?: string | null;
     };
@@ -39,15 +44,38 @@ export interface SnippetOperations {
    */
   get_org_snippet_snippet_get: {
     input: {
+    query?: {
+      /** Tracking stream to use (from GET /streams). When omitted, the organization's main stream is used: its only stream, or the one matching its website domain. */
+      stream_id?: string | null;
+    };
     headers?: {
       "X-Target-Org-Id"?: string | null;
     };
   };
     output: ApiResponse_SnippetResponse_;
   };
+  /**
+   * GET /streams
+   * List Org Streams
+   * tier: read · scope: integrations:read
+   */
+  list_org_streams_streams_get: {
+    input: {
+    query?: {
+      /** Page number (1-indexed). Omit page and limit to get every stream. */
+      page?: number | null;
+      /** Streams per page (max 200). Omit page and limit to get every stream. */
+      limit?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_StreamInfoResponse__;
+  };
 }
 
-// 4 schemas referenced above (the same as G8Contract.<Name>).
+// 6 schemas referenced above (the same as G8Contract.<Name>).
 
 export interface ApiResponse_SnippetResponse_ {
   data: SnippetResponse;
@@ -59,6 +87,11 @@ export interface ApiResponse_dict_ {
   pagination?: PaginationMeta | null;
 }
 
+export interface ApiResponse_list_StreamInfoResponse__ {
+  data: Array<StreamInfoResponse>;
+  pagination?: PaginationMeta | null;
+}
+
 export interface PaginationMeta {
   /** Whether there are more pages */
   has_next: boolean;
@@ -66,13 +99,23 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 export interface SnippetResponse {
+  /** True when the organization has several streams and none could be identified as its main website. The write key is the first stream's (unchanged legacy default); pick the right one from available_streams and call again with stream_id. */
+  action_required?: boolean;
+  /** The organization's streams to choose from. Filled only when action_required is true. */
+  available_streams?: Array<StreamInfoResponse>;
   /** Full configuration object for gtm/config.json */
   config?: Record<string, unknown>;
   domains?: Array<string>;
@@ -80,6 +123,33 @@ export interface SnippetResponse {
   react_snippet: string;
   /** Vanilla JS script tag for non-React apps */
   script_tag: string;
+  /** ID of the tracking stream the write key belongs to, when known. */
+  stream_id?: string | null;
+  /** User-friendly name of that stream, when known. */
+  stream_name?: string | null;
+  /** How the stream was chosen: 'explicit' (stream_id given), 'repo_write_key' (the repository's stored key), 'only_stream', 'domain_match' (matches the organization's website), or 'first_stream_fallback' (ambiguous; see action_required). */
+  stream_selection?: string | null;
   tracking_host?: string;
+  /** Human-readable explanation when action_required is true, or a stream setup advisory. */
+  warning?: string | null;
   write_key: string;
 }
+
+export interface StreamInfoResponse {
+  /** Domains associated with this stream */
+  domains?: Array<string>;
+  /** Whether the stream lists allowed domains. False means its public write key is accepted from any website (see warning). */
+  domains_restricted?: boolean;
+  /** Stream ID used to select this stream */
+  id: string;
+  /** True for the stream GET /snippet uses when no stream_id is given: the only stream, or the one whose domain matches the organization's website. False on every stream when that choice is ambiguous; pass stream_id explicitly then. */
+  is_default?: boolean;
+  /** User-friendly stream name (e.g. 'graph8.com', 'heyreach-graph8') */
+  name: string;
+  /** Connected repository whose stored write key belongs to this stream. Null when no connected repository uses it: streams are organization-level, not owned by a repo. */
+  repo_id?: string | null;
+  /** Read-only advisory about this stream's setup, e.g. no allowed domains. Nothing is enforced. */
+  warning?: string | null;
+  /** Public write key for this stream */
+  write_key?: string | null;
+}

package/docs/api/snippet.md

@@ -2,7 +2,7 @@
 
 # `g8.api.snippet`: Snippet
 
-2 operations (2 read).
+3 operations (3 read).
 
 1 of these also have a hand-written method (`g8.snippet`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
 
@@ -24,6 +24,7 @@ Exact TypeScript types for every operation on this page, and every schema they u
 |---|---|---|---|---|
 | [`getFormTemplate`](#op-getformtemplate) | `GET /api/v1/snippet/form` | read | `integrations:read` | Get Form Template |
 | [`getOrgSnippet`](#op-getorgsnippet) ★ | `GET /api/v1/snippet` | read | `integrations:read` | Get Org Snippet |
+| [`listOrgStreams`](#op-listorgstreams) | `GET /api/v1/streams` | read | `integrations:read` | List Org Streams |
 
 ---
 
@@ -51,7 +52,11 @@ snippet (see ``GET /snippet``). The form POSTs to your tracking host by
 default, but you can override ``action`` to route submissions to your own
 backend.
 
-**Input**: none.
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.stream_id` | `string \| null` | no | Tracking stream whose write key the form uses (from GET /streams). Defaults as in GET /snippet. |
 
 **Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -80,9 +85,16 @@ const result = await g8.api.snippet.getFormTemplate();
 Get the tracking snippet for the authenticated organization.
 
 Returns the write key and pre-built snippets without requiring a
-connected repository. Uses the org's first available tracking stream.
+connected repository. Pass `stream_id` to choose the stream; otherwise the
+org's main stream is used (its only stream, or the one whose domain matches
+the org's website). If that is ambiguous the first stream is used as before
+and the response sets `action_required` with `available_streams` to pick from.
+
+**Input**
 
-**Input**: none.
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.stream_id` | `string \| null` | no | Tracking stream to use (from GET /streams). When omitted, the organization's main stream is used: its only stream, or the one matching its website domain. |
 
 **Returns** `ApiResponse_SnippetResponse_`: the envelope `{ data: SnippetResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -95,12 +107,69 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `react_snippet` | `string` | yes | Ready-to-use React component import for @graph8/nextjs |
 | `script_tag` | `string` | yes | Vanilla JS script tag for non-React apps |
 | `write_key` | `string` | yes |  |
+| `action_required` | `boolean` | no | True when the organization has several streams and none could be identified as its main website. The write key is the first stream's (unchanged legacy default); pick the right one from available_streams and call again with stream_id. default `false` |
+| `available_streams` | `Array<StreamInfoResponse>` | no | The organization's streams to choose from. Filled only when action_required is true. |
 | `config` | `Record<string, unknown>` | no | Full configuration object for gtm/config.json |
 | `domains` | `Array<string>` | no |  |
+| `stream_id` | `string \| null` | no | ID of the tracking stream the write key belongs to, when known. |
+| `stream_name` | `string \| null` | no | User-friendly name of that stream, when known. |
+| `stream_selection` | `string \| null` | no | How the stream was chosen: 'explicit' (stream_id given), 'repo_write_key' (the repository's stored key), 'only_stream', 'domain_match' (matches the organization's website), or 'first_stream_fallback' (ambiguous; see action_required). |
 | `tracking_host` | `string` | no | default `"https://t.graph8.com"` |
+| `warning` | `string \| null` | no | Human-readable explanation when action_required is true, or a stream setup advisory. |
 
 **Example**
 
 ```ts
 const result = await g8.api.snippet.getOrgSnippet();
 ```
+
+---
+
+<a id="op-listorgstreams"></a>
+
+### `g8.api.snippet.listOrgStreams(input?)`
+
+**List Org Streams**
+
+- HTTP: `GET /api/v1/streams`
+- operationId: `list_org_streams_streams_get` (also callable as `g8.api.call("list_org_streams_streams_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `integrations:read`
+
+List the organization's tracking streams (websites) without a repository.
+
+Streams belong to the organization, not to a connected repository, so this
+works even when the org has connected no repository. Each stream carries its
+write key, its domains, `is_default` (the stream `GET /snippet` uses when no
+`stream_id` is given), `repo_id` (the connected repository already using it,
+or null), and a read-only `warning` when it has no allowed domains.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.page` | `integer \| null` | no | Page number (1-indexed). Omit page and limit to get every stream. |
+| `query.limit` | `integer \| null` | no | Streams per page (max 200). Omit page and limit to get every stream. |
+
+**Returns** `ApiResponse_list_StreamInfoResponse__`: the envelope `{ data: Array<StreamInfoResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`StreamInfoResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Stream ID used to select this stream |
+| `name` | `string` | yes | User-friendly stream name (e.g. 'graph8.com', 'heyreach-graph8') |
+| `domains` | `Array<string>` | no | Domains associated with this stream |
+| `domains_restricted` | `boolean` | no | Whether the stream lists allowed domains. False means its public write key is accepted from any website (see warning). default `false` |
+| `is_default` | `boolean` | no | True for the stream GET /snippet uses when no stream_id is given: the only stream, or the one whose domain matches the organization's website. False on every stream when that choice is ambiguous; pass stream_id explicitly then. default `false` |
+| `repo_id` | `string \| null` | no | Connected repository whose stored write key belongs to this stream. Null when no connected repository uses it: streams are organization-level, not owned by a repo. |
+| `warning` | `string \| null` | no | Read-only advisory about this stream's setup, e.g. no allowed domains. Nothing is enforced. |
+| `write_key` | `string \| null` | no | Public write key for this stream |
+
+**Example**
+
+```ts
+const result = await g8.api.snippet.listOrgStreams();
+```

package/docs/api/socialPublishing.d.ts

@@ -494,10 +494,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /** A connected social account. `id` is what `account_ref` takes everywhere else. */

package/docs/api/studioDocuments.d.ts

@@ -215,10 +215,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /**

package/docs/api/support.d.ts

@@ -83,8 +83,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }

package/docs/api/suppressions.d.ts

@@ -160,6 +160,8 @@ export interface ApiResponse_list_SuppressionRecord__ {
 }
 
 export interface BulkReinstateResponse {
+  /** Requested contact ids that match no contact (for example a mistyped id). They also appear in `skipped`. */
+  not_found?: Array<number>;
   reinstated?: Array<number>;
   skipped?: Array<ReinstateSkip>;
   total_requested: number;
@@ -167,6 +169,8 @@ export interface BulkReinstateResponse {
 
 export interface BulkSuppressResponse {
   channel: string;
+  /** Requested contact ids that match no contact; nothing was written for them. */
+  not_found?: Array<number>;
   suppressed: number;
   total_requested: number;
 }
@@ -178,10 +182,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 export interface ReinstateSkip {

package/docs/api/suppressions.md

@@ -73,6 +73,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | `channel` | `string` | yes |  |
 | `suppressed` | `integer` | yes |  |
 | `total_requested` | `integer` | yes |  |
+| `not_found` | `Array<integer>` | no | Requested contact ids that match no contact; nothing was written for them. |
 
 **Example**
 
@@ -219,6 +220,7 @@ Other envelope fields: `pagination` (PaginationMeta).
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `total_requested` | `integer` | yes |  |
+| `not_found` | `Array<integer>` | no | Requested contact ids that match no contact (for example a mistyped id). They also appear in `skipped`. |
 | `reinstated` | `Array<integer>` | no |  |
 | `skipped` | `Array<ReinstateSkip>` | no |  |
 

package/docs/api/surveys.d.ts

@@ -621,10 +621,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 export interface PerSurveyDTO {

package/docs/api/tasks.d.ts

@@ -561,10 +561,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /**

package/docs/api/teamMembers.d.ts

@@ -661,8 +661,14 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }

package/docs/api/teams.d.ts

@@ -709,10 +709,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /**

package/docs/api/usage.d.ts

@@ -209,10 +209,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /**

package/docs/api/visitors.d.ts

@@ -122,6 +122,10 @@ export interface VisitorsOperations {
       /** Comma-separated public keys, or "all". Omit for every stream. */
       stream_id?: string | null;
       limit?: number;
+      /** Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. */
+      include_bots?: boolean;
+      /** Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. */
+      include_internal?: boolean;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -189,6 +193,10 @@ export interface VisitorsOperations {
       /** Comma-separated public keys, or "all". Omit for every stream. */
       stream_id?: string | null;
       limit?: number;
+      /** Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. */
+      include_bots?: boolean;
+      /** Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. */
+      include_internal?: boolean;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -247,6 +255,12 @@ export interface VisitorsOperations {
       /** What to count. */
       resource: "contacts" | "companies";
     };
+    query?: {
+      /** Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. */
+      include_bots?: boolean;
+      /** Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. */
+      include_internal?: boolean;
+    };
     headers?: {
       "X-Target-Org-Id"?: string | null;
     };
@@ -303,6 +317,10 @@ export interface VisitorsOperations {
       page?: number;
       /** Items per page. */
       limit?: number;
+      /** Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. */
+      include_bots?: boolean;
+      /** Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. */
+      include_internal?: boolean;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -348,6 +366,10 @@ export interface VisitorsOperations {
       page?: number;
       /** Items per page. */
       limit?: number;
+      /** Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. */
+      include_bots?: boolean;
+      /** Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. */
+      include_internal?: boolean;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -370,6 +392,10 @@ export interface VisitorsOperations {
       page?: number;
       /** Items per page. */
       limit?: number;
+      /** Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. */
+      include_bots?: boolean;
+      /** Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. */
+      include_internal?: boolean;
     };
     headers?: {
       "X-Target-Org-Id"?: string | null;
@@ -576,10 +602,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /** One handler response. Open-shaped - these payloads come from the tracking pipeline. */

package/docs/api/visitors.md

@@ -227,6 +227,8 @@ Live sessions rolled up per visitor. Same PII rule as `/live`.
 | `query.time_window` | `"5min" \| "30min" \| "1hr"` | no | Live window. default `"30min"` |
 | `query.stream_id` | `string \| null` | no | Comma-separated public keys, or "all". Omit for every stream. |
 | `query.limit` | `integer` | no | default `1000` |
+| `query.include_bots` | `boolean` | no | Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. default `false` |
+| `query.include_internal` | `boolean` | no | Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. default `false` |
 
 **Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -372,6 +374,8 @@ same principal.
 | `query.time_window` | `"5min" \| "30min" \| "1hr"` | no | Live window. default `"30min"` |
 | `query.stream_id` | `string \| null` | no | Comma-separated public keys, or "all". Omit for every stream. |
 | `query.limit` | `integer` | no | default `10000` |
+| `query.include_bots` | `boolean` | no | Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. default `false` |
+| `query.include_internal` | `boolean` | no | Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. default `false` |
 
 **Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -478,6 +482,8 @@ not comparable row for row and should not be charted as if they were.
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `path.resource` | `"contacts" \| "companies"` | yes | What to count. |
+| `query.include_bots` | `boolean` | no | Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. default `false` |
+| `query.include_internal` | `boolean` | no | Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. default `false` |
 | `body` | `Array<Record<string, unknown>>` | no | Request body; fields below. |
 
 **Returns** `ApiResponse_VisitorStatisticsResponse_`: the envelope `{ data: VisitorStatisticsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
@@ -599,6 +605,8 @@ The B2BC variant of the contact feed.
 | `query.filter` | `string \| null` | no | Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. |
 | `query.page` | `integer` | no | Page number (1-indexed). default `1` |
 | `query.limit` | `integer` | no | Items per page. default `50` |
+| `query.include_bots` | `boolean` | no | Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. default `false` |
+| `query.include_internal` | `boolean` | no | Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. default `false` |
 
 **Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -685,6 +693,8 @@ Visits resolved to a company rather than a person.
 | `query.filter` | `string \| null` | no | Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. |
 | `query.page` | `integer` | no | Page number (1-indexed). default `1` |
 | `query.limit` | `integer` | no | Items per page. default `50` |
+| `query.include_bots` | `boolean` | no | Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. default `false` |
+| `query.include_internal` | `boolean` | no | Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. default `false` |
 
 **Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 
@@ -733,6 +743,8 @@ it looks.
 | `query.filter` | `string \| null` | no | Serialised filter expression, passed through to the events query unchanged. Its grammar is the app's, not this contract's - a typed model here would freeze a filter language that still moves. |
 | `query.page` | `integer` | no | Page number (1-indexed). default `1` |
 | `query.limit` | `integer` | no | Items per page. default `50` |
+| `query.include_bots` | `boolean` | no | Also count bot and crawler traffic. Off by default: events from self-identified crawlers, headless browsers, HTTP libraries and datacenter/cloud networks are excluded. default `false` |
+| `query.include_internal` | `boolean` | no | Also count internal traffic. Off by default: the graph8 app (app.graph8.com), local development hosts and your own team members (member emails and company email domains) are excluded. default `false` |
 
 **Returns** `ApiResponse_VisitorEventPage_`: the envelope `{ data: VisitorEventPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
 

package/docs/api/voice.d.ts

@@ -4308,10 +4308,16 @@ export interface PaginationMeta {
   limit: number;
   /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
   next_cursor?: string | null;
+  /** Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order. */
+  notes?: Array<string> | null;
   /** Current page number (1-indexed) */
   page: number;
   /** Total number of items */
   total: number;
+  /** Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search. */
+  total_available?: number | null;
+  /** Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search. */
+  total_is_lower_bound?: boolean | null;
 }
 
 /**