Data Collection Lifecycle

AudiencePlant Admins, Data Owners, API Consumers

Required PermissionsData Collections manage permissions

Estimated Time7 min read

Demo Referencecemento-valladolid

A Data Collection moves through a defined set of states from creation until retirement. Each state controls which edits, shares, and API operations are allowed.

The Four States

1. Draft

The collection is being built. You can freely add or remove tags and edit aliases, descriptions, display ranges, and tag transforms. Nothing is visible to external consumers yet.

• Edit metadata, tags, aliases, and transforms: Allowed
• Publish to Active: Allowed (once every tag has an alias)
• Share with external users / API consumer access: Blocked (publish first)

2. Active (Published)

The collection is live. Shares can be created and API consumers can read telemetry using the aliases you defined.

• Edit metadata and tag aliases: Allowed
• Add tags: Allowed (non-breaking additive change)
• Remove tags: Confirmation required (potentially breaking change for consumers)
• Configure tag transforms: Pause collection first
• Share with external users & API consumer access: Allowed

3. Paused

The collection is temporarily suspended. All active shares are frozen immediately and external recipients lose API access until the collection is resumed. You can still edit the collection and configure tag transforms while paused.

• Edit metadata, tags, aliases, and transforms: Allowed
• Create new shares / API consumer access: Suspended

4. Archived

The collection is permanently retired and read-only. All existing shares and API keys (both direct and share keys) are permanently revoked.

• All edits, shares, and API key creation: Blocked
• View historical metadata: Allowed

State Transitions

Draft ──(Publish)──▶ Active ◀──(Pause / Resume)──▶ Paused
                       │
                   (Archive)
                       ▼
                    Archived (irreversible)

From	To	Action	Reversible?
Draft	Active	Publish	No (use Pause instead)
Active	Paused	Pause	Yes (Resume)
Paused	Active	Resume	Yes (Pause)
Active / Paused	Archived	Archive	No

Adding and Removing Tags Safely

• Adding a tag (additive): Safe for active collections. Existing API consumers simply receive an additional field they can read or ignore.
• Removing a tag (potentially breaking): Any consumer reading that tag via a share or direct API key immediately stops receiving its data.

Recommended approach for breaking changes

Pause the collection first so external recipients are aware of maintenance, remove or adjust the tag, notify affected consumers, and then Resume.

Direct Keys vs. Share Keys

• Direct API Keys (Owner): Can be created in Draft, Active, and Paused states to test before publishing or resuming. Archived revokes all direct keys permanently.
• Share API Keys (External Consumer): Tied to both the share status and the collection status. Recipients can read data only when the collection is Active, the share is active with can_use_api enabled, and the key has not expired or been revoked.

Related Guides

• Data Collections Guide
• Data Collections Read API