Reference

Preview sample records

preview_records: Returns up to 25 masked sample rows (10 by default) for an audience or a count id, each with verification badges, why it matches and a provenance card.

Generated from the contractsView as Markdown

Returns up to 25 masked sample rows (10 by default) for an audience or a count id, each with verification badges, why it matches and a provenance card. Use it after count_audience to show the user what the records look like before quoting. Free: emails and phones are masked on the server, a repeat returns the same rows, and no rows come back when the count is under 25. Call quote_order next to price the records. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

Property	Value
Tool name	`preview_records`
Position in tools/list	9 of 22
Cost	Free
Scope	None. Works without an account.
Annotations	readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Kind	Read only; idempotent, not destructive, closed world
REST equivalent	`POST /v1/previews`

Input

The schema sets additionalProperties to false, so a member that is not listed is refused.

Member	Type	Required	Description
`audience`	string or `Audience`	no	An audience definition (mydatahub.audience/1) inline, or the aud_ id of a saved audience.
`count_id`	string	no	A count id instead of an audience.
`limit`	integer (1 to 25)	no	Rows to return, 1 to 25. Default 10. Default `10`.
`shuffle`	boolean	no	Draw a new seed. Counts against your rate budget and is logged. Default false, so a repeat returns the same rows. Default `false`.

Example call

The params of a tools/call request:

{
  "name": "preview_records",
  "arguments": {
    "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
    "limit": 10
  }
}

Output

The result carries structuredContent that matches this schema, and one line of text that leads with the number.

Member	Type	Always present	Description
`id`	string	yes	Format: a preview id: prv_ followed by a 26 character ULID in upper case Crockford base32, such as prv_01JB4H3M7Q2V7XN3M9R6T1Y5W8.
`count_id`	string	yes	Format: a count id: cnt_ followed by 20 base32 characters (A to Z and 2 to 7), such as cnt_7K2PQ4MAXN3R6TBY5WDZ.
`dataset_version`	string	yes	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`seed`	string	yes	The seed the rows came from; the same audience gives the same seed.
`count`	integer (0 or more)	yes	The count the rows were drawn from, rounded as disclosure says.
`disclosure`	`Disclosure`	yes	Whether these numbers are exact or protected: "under 10" cells, rounding to 5 and secondary suppression for anonymous and trial callers.
`disclosure.level`	enum: `exact`, `rounded`	yes	exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.
`disclosure.rounded_to`	integer or null	yes	5 when numbers are rounded; null when they are exact.
`disclosure.secondary_suppression`	boolean	yes	True when cross-tab or breakdown cells of 10 or more were hidden as "suppressed" so totals cannot be differenced.
`disclosure.notes`	array of string	yes
`rows`	array of `PreviewRow`	yes
`rows[].id`	string	yes	A session-scoped id standing in for the record. It never reveals contact_ ids.
`rows[].title`	string	yes
`rows[].job_level`	string or null	yes	The level, such as Director; null when the level is not known.
`rows[].job_function`	string or null	yes
`rows[].company`	object	yes
`rows[].site`	object	yes
`rows[].email_masked`	string or null	yes	First character of the local part plus the top level domain, such as j••••@••••.co.uk.
`rows[].email_type`	enum: `named`, `generic_local_part`, `generic_domain` or null	yes
`rows[].phone_masked`	string or null	yes	To the area code, such as 0113 ••• •••1.
`rows[].tps_ctps_status`	enum: `clear`, `tps_registered`, `ctps_registered`, `tps_or_ctps_registered`, `not_screened` or null	yes
`rows[].badges`	array of `VerifiedBadge` or `OtherBadge`	yes
`rows[].why_it_matches`	array of `WhyItMatches`	yes
`rows[].provenance`	`ProvenanceCard`	yes	The ICO due diligence answers for one record, as shown on the sample row.
`rows[].compliance`	`ComplianceObject`	yes	Carried by every preview row, order record, lookup and enrichment, and repeated as CSV columns and as the MyDataHub property group on CRM push.
`withheld`	object or null	yes	Rows held back: all of them when the count is under 25, or rows whose title fewer than 10 people hold.
`withheld.rows`	integer (0 or more)	yes
`withheld.reason`	string	yes
`masked`	`true`	yes
`watermark`	string or null	yes	The account id watermarked into sample CSVs; null when signed out.
`created_at`	string (date-time)	yes

Errors

A failed call returns isError true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with code, detail, next_step and did_you_mean. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See Errors.