Installation
pip install administrate
Requires Python 3.9 or later. Dependencies: httpx and pydantic.
Authentication
Create an API key in Settings > Developers, then pass it when initializing the client:
from administrate import Administrate
client = Administrate(api_key="sk_live_...")
Quick start
# Get account info
account = client.account.get()
print(f"{account.name} ({account.plan})")
# List all clients
for c in client.clients.list():
print(c.name, c.n8n_instances_count)
# Get failed executions
for ex in client.executions.list(errors_only=True):
print(f"{ex.workflow_name}: {ex.error_category}")
Async support
The SDK includes an async client with the same interface:
from administrate import AsyncAdministrate
client = AsyncAdministrate(api_key="sk_live_...")
account = await client.account.get()
executions = await client.executions.list(status="failed")
Common operations
Monitor failing workflows
executions = client.executions.list(
status="failed",
start_date="2026-01-01",
end_date="2026-01-31",
)
for ex in executions:
print(f"{ex.workflow_name}: {ex.error_category}")
Trigger a sync
client.instances.sync("n8n_abc123", sync_type="all")
Check sync health
for entry in client.sync_runs.health():
print(f"{entry.instance_name}: {entry.sync_status}")
Pagination
List methods auto-paginate by default. You can also control pagination manually:
page = client.executions.list(page=1, per_page=50)
print(page.meta.total, page.meta.total_pages)
Error handling
from administrate.errors import NotFoundError, AuthenticationError
try:
client.instances.get("n8n_nonexistent")
except NotFoundError:
print("Instance not found")
except AuthenticationError:
print("Invalid API key")