Insights API

The Insights API provides analytics and monitoring data for your SignalSmith workspace. Use it to track sync health, audience trends, activation coverage, and audience overlap.

Endpoints

Method	Path	Description
`GET`	`/api/v1/workspaces/{id}/insights/sync-health`	Sync health overview
`GET`	`/api/v1/workspaces/{id}/insights/audience-trends`	Audience size trends
`GET`	`/api/v1/workspaces/{id}/insights/activation-coverage`	Activation coverage
`GET`	`/api/v1/workspaces/{id}/insights/audience-overlap`	Audience overlap analysis
`GET`	`/api/v1/workspaces/{id}/insights/summary`	Dashboard summary

Sync Health

GET /api/v1/workspaces/{id}/insights/sync-health

Returns health metrics for all syncs in the workspace, including success rates, failure counts, and recent run history.

Query Parameters

Parameter	Type	Default	Description
`days`	integer	`7`	Number of days to look back

Response

{
  "total_syncs": 12,
  "active_syncs": 10,
  "healthy_syncs": 9,
  "failing_syncs": 1,
  "paused_syncs": 2,
  "syncs": [
    {
      "sync_id": "550e8400-e29b-41d4-a716-446655440000",
      "sync_name": "Customers to Salesforce",
      "status": "active",
      "last_run_status": "completed",
      "last_run_at": "2024-01-15T15:00:00Z",
      "success_rate": 0.98,
      "total_runs": 42,
      "failed_runs": 1,
      "avg_duration_seconds": 145,
      "total_rows_synced": 125000
    }
  ]
}

Example

curl -X GET "https://your-instance.signalsmith.io/api/v1/workspaces/{id}/insights/sync-health?days=7" \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Audience Trends

GET /api/v1/workspaces/{id}/insights/audience-trends

Returns audience size changes over time for selected audiences.

Query Parameters

Parameter	Type	Default	Description
`audience_ids`	string (comma-separated)	All	Audience IDs to include
`days`	integer	`30`	Number of days to look back

Response

{
  "audiences": [
    {
      "audience_id": "550e8400-e29b-41d4-a716-446655440000",
      "audience_name": "High-Value Customers",
      "data_points": [
        {"date": "2024-01-01", "size": 4100},
        {"date": "2024-01-08", "size": 4200},
        {"date": "2024-01-15", "size": 4250}
      ],
      "current_size": 4250,
      "change_absolute": 150,
      "change_percent": 3.66
    }
  ]
}

Example

curl -X GET "https://your-instance.signalsmith.io/api/v1/workspaces/{id}/insights/audience-trends?days=30" \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Activation Coverage

GET /api/v1/workspaces/{id}/insights/activation-coverage

Shows which audiences are being synced to which destinations, and identifies gaps in activation.

Response

{
  "total_audiences": 15,
  "activated_audiences": 12,
  "unactivated_audiences": 3,
  "destinations": [
    {
      "destination_id": "550e8400-e29b-41d4-a716-446655440000",
      "destination_name": "Google Ads",
      "destination_type": "google_ads",
      "audience_count": 8,
      "audiences": [
        {
          "audience_id": "660e8400-e29b-41d4-a716-446655440000",
          "audience_name": "High-Value Customers",
          "sync_status": "active",
          "last_synced_at": "2024-01-15T15:00:00Z"
        }
      ]
    }
  ],
  "unactivated": [
    {
      "audience_id": "770e8400-e29b-41d4-a716-446655440000",
      "audience_name": "Churned Users",
      "estimated_size": 850
    }
  ]
}

Audience Overlap

GET /api/v1/workspaces/{id}/insights/audience-overlap

Analyzes the overlap between two or more audiences to help identify redundancy or opportunities for exclusion targeting.

Query Parameters

Parameter	Type	Required	Description
`audience_ids`	string (comma-separated)	Yes	Two or more audience IDs to compare

Response

{
  "audiences": [
    {"id": "550e8400-...", "name": "High-Value", "size": 4250},
    {"id": "660e8400-...", "name": "Recent Buyers", "size": 8100}
  ],
  "overlap": {
    "size": 3200,
    "percent_of_first": 75.3,
    "percent_of_second": 39.5
  }
}

Example

curl -X GET "https://your-instance.signalsmith.io/api/v1/workspaces/{id}/insights/audience-overlap?audience_ids=550e8400-...,660e8400-..." \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Dashboard Summary

GET /api/v1/workspaces/{id}/insights/summary

Returns a high-level summary of the workspace’s activity for the dashboard.

Response

{
  "sources": {
    "total": 3,
    "connected": 3,
    "error": 0
  },
  "models": {
    "total": 12,
    "active": 10
  },
  "destinations": {
    "total": 8,
    "connected": 7,
    "error": 1
  },
  "syncs": {
    "total": 15,
    "active": 12,
    "paused": 2,
    "error": 1,
    "rows_synced_today": 45000
  },
  "audiences": {
    "total": 20,
    "active": 18,
    "total_members": 125000
  },
  "loaders": {
    "total": 4,
    "active": 3,
    "rows_loaded_today": 28000
  }
}

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/insights/summary \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Govern Workspaces