Skip to main content

​
Get Tenant Migrations

Retrieve migration status for all tenants, showing pending migrations and database provider information. 
GET /api/v1/tenants/migrations

​
Authorization

Requires Permissions.Multitenancy.View permission.

​
Response

Returns an array of tenant migration status objects.
​
tenantId
string
Unique tenant identifier
​
name
string
Tenant display name
​
isActive
boolean
Whether the tenant is currently active
​
validUpto
datetime
Subscription expiration date
​
hasPendingMigrations
boolean
Whether there are unapplied database migrations
​
provider
string
Database provider (e.g., “PostgreSQL”, “SqlServer”, “MySql”)
​
lastAppliedMigration
string
Name of the most recently applied migration
​
pendingMigrations
array
List of migration names that have not been applied
​
error
string
Error message if migration status check failed
[
  {
    "tenantId": "root",
    "name": "Root Tenant",
    "isActive": true,
    "validUpto": "2026-12-31T23:59:59Z",
    "hasPendingMigrations": false,
    "provider": "PostgreSQL",
    "lastAppliedMigration": "20260301_AddAuditingModule",
    "pendingMigrations": [],
    "error": null
  },
  {
    "tenantId": "acme-corp",
    "name": "Acme Corporation",
    "isActive": true,
    "validUpto": "2026-06-30T23:59:59Z",
    "hasPendingMigrations": true,
    "provider": "SqlServer",
    "lastAppliedMigration": "20260201_InitialCreate",
    "pendingMigrations": [
      "20260215_AddIdentityModule",
      "20260301_AddAuditingModule"
    ],
    "error": null
  },
  {
    "tenantId": "broken-tenant",
    "name": "Broken Tenant",
    "isActive": false,
    "validUpto": "2025-12-31T23:59:59Z",
    "hasPendingMigrations": false,
    "provider": null,
    "lastAppliedMigration": null,
    "pendingMigrations": [],
    "error": "Failed to connect to database: Connection timeout"
  }
]

​
Understanding Migration Status

​
No Pending Migrations

When hasPendingMigrations is false, the tenant’s database is up to date: 
{
  "tenantId": "root",
  "hasPendingMigrations": false,
  "lastAppliedMigration": "20260301_AddAuditingModule",
  "pendingMigrations": []
}

​
Pending Migrations

When hasPendingMigrations is true, the tenant needs database updates: 
{
  "tenantId": "acme-corp",
  "hasPendingMigrations": true,
  "lastAppliedMigration": "20260201_InitialCreate",
  "pendingMigrations": [
    "20260215_AddIdentityModule",
    "20260301_AddAuditingModule"
  ]
}
Tenants with pending migrations may experience issues with new features. Apply migrations promptly.

​
Migration Errors

If migration status cannot be determined, the error field contains details: 
{
  "tenantId": "broken-tenant",
  "hasPendingMigrations": false,
  "error": "Failed to connect to database: Connection timeout"
}

​
Use Cases

​
Health Monitoring

Use this endpoint to monitor database health across all tenants:
  • Identify tenants with pending migrations
  • Detect database connection issues
  • Verify migration deployment success

​
Pre-Deployment Checks

Before deploying new application versions:
  1. Check for pending migrations
  2. Apply migrations to test tenants first
  3. Monitor for errors
  4. Roll out to production tenants

​
Multi-Database Support

The provider field helps manage heterogeneous database environments:
  • Track which tenants use which database providers
  • Target provider-specific optimizations
  • Plan database upgrades
This endpoint queries all tenant databases. Response time may increase with large numbers of tenants.

Build docs developers (and LLMs) love

Get started for freeTalk to us