Salesforce Archive

Operate Salesforce Archive (also called Trusted Services Archive) through its Connect API and the

ArchiveActivity

job-metadata object. This skill covers how to search and restore archived records, run the analyzer, handle RTBF erasure and PII masking, check storage, and — the part most often missed — how to read archive job status from

ArchiveActivity

and use a job's Id + Type to download its logs.

Scope

In scope: Calling the Archive Connect API operations under
```
/platform/data-resilience/archive/
```
; querying the
```
ArchiveActivity
```
object via SOQL/Connect; correlating a job's
```
ArchiveActivity
```
record with its log-download endpoints; the verify-after-write pattern for each async operation.
Out of scope: Defining archive policies /
```
ArchivePolicyDefinition
```
metadata; building UI; generating Flows over archive data (
```
ArchiveActivity
```
is not Flow-queryable — see Gotchas); generic backup/export tooling unrelated to the add-on.

Required Inputs

Gather or infer before acting:

Operation intent: search (this is also how you view archived records), unarchive, analyze, mask, RTBF, storage check, or job-status/log lookup.
Target sObject (
```
sobjectName
```
): required for search and unarchive.
Filters: search and unarchive require
```
sobjectName
```
+ at least one filter.
For log downloads: the
```
requestId
```
(an
```
ArchiveActivity
```
Id,
```
8qv…
```
prefix) of a completed, log-producing job, and
```
reportType
```
= that activity's
```
Type
```
.

Preconditions (confirm or surface to the user if a call returns a not-permitted error):

The org must have Salesforce Archive enabled. Every operation is gated on this first.
Each operation requires a specific user permission on top of the org gate — see the Permissions table below. There is no single "archive admin" role; access is per-capability.

Permissions

Every operation first requires the org to have Salesforce Archive enabled. On top of that org gate, each capability is gated by a distinct user permission. A call the user isn't permitted for fails with a "not permitted" error — match the error to the missing permission below.

Operation	User permission required
`search-archived-records` , `get-search-archived-records-next-page`	`ViewSearchPage` (Archive Search) — not `ViewArchivedRecords`
`search-archived-records-with-sharing-rules`	`ViewArchivedRecords`
`unarchive-records`	`UnarchiveSdk`
`forget-archived-records` (RTBF) + `get-rtbf-status`	`Rtbf`
`mask-archived-records` + `get-masking-status`	`Rtbf` (masking shares the same `Rtbf` permission — not a separate entitlement)
`run-analyzer` , `get-analyzer-report` , `get-archive-storage-used`	`ArchiveAnalyzer`
`get-execution-details-stream-url` , `get-failed-records-stream-url`	`ViewActivitiesPage` (Archive Activities)

Workflow

All steps are sequential within a task. Read the referenced file the first time you touch that area.

Identify the operation and read the contract — do not rely on general knowledge of the Archive API, which has non-obvious contracts. Load
```
references/connect-api-operations.md
```
for the exact request/response shape, required inputs, and per-operation gotchas of every Archive Connect API operation. Do this before constructing any call (e.g.
```
dateRanges
```
plural vs singular,
```
isSuccess
```
flag vs HTTP status,
```
url: null
```
meaning no log).
For job status / monitoring, read the data model — when the task involves archive jobs, failures, progress, counts, or logs, load
```
references/archive-activity-entity.md
```
for the
```
ArchiveActivity
```
field reference and how it links to the Connect API. Query
```
ArchiveActivity
```
via SOQL or Connect — not Flow. For a worked end-to-end example (find failed/in-progress jobs, then pull their execution-detail and failed-records logs), load
```
examples/monitor-failed-jobs.md
```
.

Construct and send the call — every operation is a

{method, path, body}

REST call. Send it with whatever Connect/REST API tool your environment provides (an MCP server that invokes Connect/REST APIs, the

sf

CLI, or any REST client). Two path rules are critical (full per-operation contracts are in

references/connect-api-operations.md

The operation names in this skill are NOT URL paths.
```
search-archived-records
```
,
```
unarchive-records
```
, etc. are labels; never put them in the path. Use the short literal paths below (each relative to base
```
/platform/data-resilience/archive
```
). Sending the operation name as a path segment (e.g.
```
/…/archive/search-archived-records
```
) returns 404.
The path stops at
/platform/data-resilience/archive/…
— there is NO
/connect
segment, even though this is a Connect API. A 404 /
NOT_FOUND
here means the path is wrong, NOT that Archive is disabled — fix the path before concluding the add-on is missing.

Operation	Method + Path	Notes
search-archived-records	`POST /search`	requires `sobjectName` + ≥1 filter
search next page	`GET /search/next/{scrollId}`	stop when `scroll_id == "-1"`
search with sharing rules	`POST /search/with-sharing-rules`	uses `filtersJson` object map
unarchive-records	`POST /unarchive`	`sobjectName` + filters
run-analyzer / report	`POST /analyzer/run` · `GET /analyzer/report`
forget / RTBF + status	`POST /rtbf` · `GET /rtbf/{requestId}`
mask + status	`POST /mask` · `GET /mask/{requestId}`
storage used	`GET /storage/archive-used`
execution-detail / failed-records log	`GET /log/execution-details-stream-url` · `GET /log/failed-records-stream-url`	query params `requestId` , `reportType`

With the

sf

CLI, prefix the path with

/services/data/v67.0

; some MCP/REST tools take the bare path and add the version themselves (tool-dependent — see the reference). Then follow the contract: for searches, supply

sobjectName

+ ≥1 filter; for date filtering use the plural

dateRanges

array of

{field, from, to}

with full ISO-8601 datetimes.

Branch on the right signal — some operations return HTTP 201 with a body-level success flag (
```
body.statusCode
```
,
```
body.isSuccess
```
). Read
```
references/connect-api-operations.md
```
for which signal to trust per operation; never assume the HTTP status alone means success.
Verify after every write — re-read state to confirm the effect (see the Verify-After-Write table below). Async operations (analyzer, RTBF, masking) return a request id you must poll.

Verify-After-Write

After this write	Confirm by
`run-analyzer`	Poll `get-analyzer-report` until the report is populated
`unarchive-records`	Re-run `search-archived-records` — confirm records left the archive
`forget-archived-records` (RTBF)	Poll `get-rtbf-status` with the returned `request_id`
`mask-archived-records`	Poll `get-masking-status` with the returned `request_id`

Rules / Constraints

Constraint	Rationale
Search & unarchive require `sobjectName` + at least one filter	An unfiltered request is rejected with "Search must be based on at least 1 field" — a full-object operation is never allowed.
Date filters must be full ISO-8601 datetimes ( `2020-01-01T00:00:00Z` )	A date-only value ( `2020-01-01` ) returns `400 JSON_PARSER_ERROR` because the field is typed `xsd:dateTime` .
Search uses `dateRanges` (plural array); unarchive uses `dateRange` (singular)	They are genuinely different fields on the two endpoints; using the wrong shape silently drops the filter or 400s.
Stop pagination when `scroll_id == "-1"`	Calling `get-search-archived-records-next-page` with `"-1"` returns 500.
Log downloads need a real `ArchiveActivity` Id as `requestId` + that activity's `Type` as `reportType`	The backend resolves the log by the activity record; a mismatched `reportType` returns no log.
Excluded objects are not retrievable	`Feed` , `History` , `Relation` , `Share` are not searchable; Files/Attachments are not retrievable via this API — do not promise them.
Query `ArchiveActivity` via SOQL/Connect, never Flow	`ArchiveActivity` has `isProcessEnabled=false` , so a Flow "Get Records" element on it fails with "You can't get ArchiveActivity records in a flow."

Gotchas

Issue	Resolution
Treating HTTP 201 as success	Several operations return 201 with a body-level outcome. Branch on `body.statusCode` (search) or `body.isSuccess` ( `with-sharing-rules` ), not the HTTP code.
`run-analyzer.isRunning` used as a signal	It is always `null` ; the endpoint only populates `message` . Poll `get-analyzer-report` to confirm completion instead.
`search-archived-records-with-sharing-rules` filters as an array	`filtersJson` must be a JSON-encoded object map `{"Field":"Value"}` , not an array of `{field,value}` ; the array form returns `isSuccess:false "No valid filters provided"` .
Log `url` treated as present because status is 201	`get-*-stream-url` returns `{url}` ; `url: null` means no log was resolved. Always check `url != null` .
Misreading `get-archive-storage-used`	`usedStorage[]` / `availableStorage[]` are parallel positional arrays: index 0=org DATA, 1=org FILE, 2=archive RECORDS, 3=archive FILE. `availableStorage[2]` / `[3]` are always 0 (archive tier is unmetered) — that means "not tracked", not "full".
Expecting `ArchiveActivity` in a Flow	It is not Flow-enabled ( `isProcessEnabled=false` ). Use SOQL/Connect/Reports.
Hitting unarchive caps	Unarchive processes ≤1000 matched records per request and ≤50 requests/hour/org, and restores the whole archived hierarchy of each match.
RTBF/masking caps	`criteria` ≤10 entries (one per object); ≤10,000 root records/day (shared between RTBF and masking); masking is irreversible. Both RTBF and masking are gated by the same `Rtbf` user permission.

Output Expectations

This is a knowledge/API skill — it produces API calls and their interpreted results, plus SOQL against

ArchiveActivity

. It does not generate deployable metadata. Deliverables per task: the correct operation invocation(s), the right success-signal branching, and a verify-after-write confirmation.

Reference File Index

File	When to read
`references/connect-api-operations.md`	Before constructing any Archive Connect API call — full per-operation contracts, success signals, and limits
`references/archive-activity-entity.md`	For any job-status / failure / progress / log task — `ArchiveActivity` field reference and its link to the log-download endpoints
`examples/monitor-failed-jobs.md`	To follow an end-to-end monitoring flow: find failed/in-progress jobs, then download their logs

platform-trust-archive-manage

NPX Install

Tags

SKILL.md Content