docs(audiences): document Salesforce export full-load behavior, API monitoring, and Last Enriched timestamp

[george-dilthey]

What changed

Added three pieces of missing information to docs/audiences.md about Audiences→Salesforce export sync, plus corrected a wrong batch-size claim already in the docs.

1. First export is a full load: Expanded the "First export" bullet in "Export sync behavior" to explicitly state the first export processes all records as a full load — not just recently changed ones — explaining why it takes longer at high volume. Previously the docs said only "Subsequent syncs: Incremental," implying but never stating the first is a full load.

2. API usage card for monitoring: Added a new "Monitoring" bullet describing the API usage card on the Salesforce source settings page — shows daily Bulk API quota and calls in the last 24 hours. Also replaced the wrong "To estimate API calls, divide record count by 10,000" line with guidance to use the API usage card. Previously absent from the docs entirely.

3. New FAQ — "How do I keep a 'Clay Last Enriched' date current in Salesforce?": Describes the formula-column timestamp pattern: add a formula column returning the current timestamp (DateTime: new Date()?.toISOString?.() or Date: new Date()?.toISOString?.()?.split?.("T")?.[0]), map with Always write. Includes the caveat that the timestamp updates on every re-run even when enrichment data hasn't changed.

4. Corrected wrong batch-size claim (existing bug): The existing doc stated "Export batch size: ~10,000 records per batch" and the "Do the API math" best practice said "or by 10,000 for export." Verifier returned FAIL — exports batch by 100 MB file size, not record count. The 10,000 figure is the Salesforce import prefetch limit, not the export batch size. Removed the wrong bullet and updated the API math best practice accordingly.

Why

Intercom conversation #215475628567527: Wendy Lac (Anrok, Enterprise) asked three questions about Audiences→Salesforce sync that Fin could not answer, requiring escalation to a human agent (Bo Morin). All three were legitimate operational questions about documented behavior that simply wasn't documented:

1. How long does the first sync take at high volume?
2. Is there any way to see sync progress or confirm records are being updated?
3. How do we manage a "Clay Last Enriched" field that updates on every enrichment?

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475628567527
• Slack thread (human agent reply): https://clay-hq.slack.com/archives/C0BM1M6QR4H/p1787615310436759?thread_ts=1787614551.753679&cid=C0BM1M6QR4H
• Code (full load / incremental export): services/audiences/src/materialization/services/export-handler.ts:3307-3309 — logger.info('No previous exports found, performing full export', ...) when lastExport is null; incremental filter f.updated_at > lastExportCreatedAt on subsequent runs
• Code (API usage card): apps/frontend/src/components/Audiences/AudienceFieldMappingForms/SalesforceApiUsageCard.tsx — renders "API usage", "Last 24 hours", "Calls used: X / Y"
• Code (export toggle + 24h schedule): libs/api-contract/src/audiences/lib/import-types.ts:881-882; services/scheduler/src/bull/queues/audience-export-queue.ts:13
• Code (Always write + formula timestamp mechanism): export-handler.ts:349 buildAlwaysWriteFieldColumn; import-types.ts:49 MappingRule.AlwaysWrite
• Code (batch-size FAIL): services/big-source-sync/src/services/domain/salesforce/salesforce-bulk-export.ts:113 — chunkSizeMB: 100 (file-size based, not record-count based)
• Corroborating Slack (formula timestamp pattern for same use case): https://clay-hq.slack.com/archives/C0B0JTY9V7Y/p1783536862496109?thread_ts=1783524383.006109&cid=C0B0JTY9V7Y

Uncertainties

None — all changes verified against product code. Audiences overall requires EnableAudiencesGA per-workspace flag (default false), but this is an entitlement gate for the whole Audiences product, not a flag for any individual behavior documented here.

Note on batch-size correction: the human support agent cited "roughly 10,000 records per batch" — a plausible estimate that presumably reflects typical record sizes relative to the 100 MB chunk limit. The code unambiguously uses file-size chunking, not record-count chunking, so the existing claim was removed rather than corrected with a potentially misleading approximation.

Related observations

Many other PRs are currently open on docs/audiences.md (e.g., #2179, #2184, #2192, #2202–#2205, #2210, #2215, #2224–#2225, #2231–#2232, #2245, #2251, #2261, #2272, #2280, #2288–#2291, #2295, #2303, #2305, #2321, #2323, #2345, #2348, #2349). All cover separate, non-overlapping topics — verified. This PR's changes (export sync behavior, API monitoring card, "Clay Last Enriched" FAQ, batch-size correction) appear in none of them. Reviewers should expect merge conflicts given the high concurrent edit volume on this file.

PR #2303 adds a formula-column date pattern for a different use case (timed segment entry via Upsert Audiences Record). The new FAQ in this PR addresses a different question: keeping a Salesforce timestamp current via the native Audiences export sync. Different mechanism (export mapping vs Upsert), different customer question.

Closes DOC-2110

[linear-code]

DOC-2110