Activations API

The Activations API manages segment activations -- the records that track which classified topics have been pushed to external DSP platforms (LiveRamp, Trade Desk, Index Exchange). Use these endpoints to list active segments, deactivate segments on platforms, refresh stale activations, and perform bulk operations.

List Activations

Retrieve all segment activations for your organization with optional filters.

GET /api/activations

Auth: API key with activations scope, or Clerk session

Query Parameters

Parameter	Type	Description
connectionId	string	Filter by connection ID
platform	string	Filter by platform (e.g., liveramp, tradedesk, indexexchange)
status	string	Filter by status: pending, active, deactivated, error
stale	boolean	When true, return only stale activations (pushed name/version differs from current)

Response (200)

[
  {
    "id": "act_01...",
    "orgTopicId": "ot_01hy...",
    "connectionId": "conn_01...",
    "platform": "liveramp",
    "topicName": "Tesla Model 3 Buyers",
    "status": "active",
    "platformSegmentId": "lr_seg_12345",
    "pushedName": "Auto > EV > Tesla Model 3 Buyers",
    "pushedDescription": "In-market consumers researching Tesla Model 3...",
    "engineVersionAtPush": "2.5",
    "currentPlatformName": "Auto > EV > Tesla Model 3 Buyers",
    "currentPlatformDesc": "In-market consumers researching Tesla Model 3...",
    "currentEngineVersion": "2.5",
    "activatedAt": "2026-02-20T10:00:00.000Z",
    "createdAt": "2026-02-20T09:55:00.000Z"
  }
]

curl Example

# List all active LiveRamp activations
curl "https://app.audiencegpt.com/api/activations?platform=liveramp&status=active" \
  -H "Authorization: Bearer txadv_your_api_key"

# List only stale activations (need refresh)
curl "https://app.audiencegpt.com/api/activations?stale=true" \
  -H "Authorization: Bearer txadv_your_api_key"

---

Deactivate a Single Activation

Deactivate a segment on the external platform, then mark the activation record as deactivated.

POST /api/activations/:id/deactivate

Auth: API key with activations scope, or Clerk session with activate permission

Max duration: 30 seconds

Path Parameters

Parameter	Type	Description
id	string	Activation ID

Response (200)

Returns the updated activation record with status: "deactivated":

{
  "id": "act_01...",
  "status": "deactivated",
  "deactivatedAt": "2026-02-25T12:00:00.000Z"
}

Error Responses

Status	Body	Description
404	{"error": "Activation not found"}	Invalid activation ID
409	{"error": "Activation is deactivated, cannot deactivate"}	Already deactivated
502	{"error": "Platform deactivation failed"}	Platform API error

---

Refresh a Stale Activation

Refresh a stale activation by deactivating the old segment on the platform and creating a new one with current naming. This is a 4-step process:

1. Deactivate the old segment on the platform
2. Mark the old activation as deactivated
3. Create a new segment on the platform with current naming
4. Create a new activation record with the new platform segment ID

POST /api/activations/:id/refresh

Auth: API key with activations scope, or Clerk session with activate permission

Max duration: 30 seconds

Response (200)

Returns the new activation record:

{
  "id": "act_02...",
  "status": "active",
  "platformSegmentId": "lr_seg_67890",
  "pushedName": "Auto > EV > Tesla Model 3 Buyers (Updated)",
  "activatedAt": "2026-02-25T12:00:00.000Z"
}

Error Responses

Status	Body	Description
404	{"error": "Activation not found"}	Invalid activation ID
409	{"error": "Activation is deactivated, must be active to refresh"}	Not active
502	{"error": "Failed to deactivate old segment on platform"}	Platform API error
502	{"error": "Failed to create new segment on platform"}	Platform API error

info

Stale activations occur when a topic has been reclassified (new engine version or naming changes) after being pushed to a platform. The pushed name/version no longer matches the current state.

---

Bulk Deactivate

Deactivate multiple activations in a single request.

POST /api/activations/bulk-deactivate

Auth: API key with activations scope, or Clerk session with activate permission

Max duration: 60 seconds

Request Body

{
  "activationIds": ["act_01...", "act_02...", "act_03..."]
}

Field	Type	Required	Description
activationIds	string[]	Yes	Activation IDs to deactivate (max 500)

Response (200)

{
  "total": 3,
  "success": 2,
  "errors": 1,
  "results": [
    { "activationId": "act_01...", "status": "deactivated" },
    { "activationId": "act_02...", "status": "deactivated" },
    { "activationId": "act_03...", "status": "error", "error": "Platform deactivation failed" }
  ]
}

---

Bulk Refresh

Refresh multiple stale activations in a single request.

POST /api/activations/bulk-refresh

Auth: API key with activations scope, or Clerk session with activate permission

Max duration: 60 seconds

Request Body

{
  "activationIds": ["act_01...", "act_02..."]
}

Response (200)

{
  "total": 2,
  "success": 2,
  "errors": 0,
  "results": [
    { "activationId": "act_01...", "status": "refreshed", "newActivationId": "act_04..." },
    { "activationId": "act_02...", "status": "refreshed", "newActivationId": "act_05..." }
  ]
}

---

Activation Lifecycle

pending  -->  active  -->  deactivated
                 |
                 v
         stale (detected)  -->  refresh  -->  new active

Status	Description
pending	Activation record created, not yet pushed to platform
active	Successfully pushed to platform
deactivated	Deactivated on platform
error	Push failed

Stale detection is not a status but a computed property: an activation is stale when the pushed name, description, or engine version differs from the current topic values.

---

Hygiene Routes

The hygiene endpoints manage activation health at the organization level.

Create Hygiene Refresh Job

POST /api/hygiene/refresh

Creates a background job to refresh all stale activations.

Check Hygiene Refresh Status

GET /api/hygiene/refresh/:jobId

Process Hygiene Refresh Chunk

POST /api/hygiene/refresh/:jobId/process

Processes a batch of stale activations within the refresh job.

---

TypeScript Example

// List stale activations and refresh them
async function refreshStaleActivations() {
  // Get stale activations
  const response = await fetch(
    "https://app.audiencegpt.com/api/activations?stale=true",
    { headers: { "Authorization": `Bearer ${API_KEY}` } }
  );
  const staleActivations = await response.json();

  if (staleActivations.length === 0) {
    console.log("No stale activations found");
    return;
  }

  // Bulk refresh
  const refreshRes = await fetch(
    "https://app.audiencegpt.com/api/activations/bulk-refresh",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        activationIds: staleActivations.map((a: { id: string }) => a.id),
      }),
    }
  );

  return refreshRes.json();
}

Next Steps

• Connections API -- Manage platform connections
• Topics API -- View and manage activated topics
• Rate Limits -- Activation batch limits
• Error Codes -- Platform-specific error handling