API Reference

Auto-generated

B2B

API reference for b2b endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

GET /api/v1/b2b/deliveries

GET

/api/v1/b2b/deliveries

Get delivery history (B2B enterprise tenants only)

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	Page size — number of receipts to return (1–200, default 50).Default: `50`
offset	`integer`	Optional	0-based row offset for pagination (default 0).Default: `0`
status	`"success" \| "failure"`	Optional	Optional filter by delivery outcome. Accepted values: 'success', 'failure'. When omitted, all statuses are returned.
delivery_type	`"s3" \| "webhook" \| "polling" \| "batch_export"`	Optional	Optional filter by delivery method. Accepted values: 's3', 'webhook', 'polling', 'batch_export'. When omitted, all delivery types are returned.
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/deliveries \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": [],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "filters": {}
}

GET /api/v1/b2b/health

GET

/api/v1/b2b/health

B2B org-scoped health aggregator

Parameters

Name	Type	Required	Description
window	`"24h" \| "7d" \| "30d"`	Optional	Aggregation window: '24h' (last 24 hours), '7d' (last 7 days), '30d' (last 30 days).Default: `24h`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/health \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "window": "example",
  "ad_fill_rate": "example",
  "ad_fill_rate_jobs": "example",
  "serp_success_rate": "example",
  "serp_success_rate_jobs": "example",
  "delivery_success_rate": "example"
}

GET /api/v1/b2b/jobs

GET

/api/v1/b2b/jobs

List bulk submissions (B2B enterprise tenants only)

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	Page size (max 100).Default: `20`
offset	`integer`	Optional	Number of records to skip.Default: `0`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": [],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "has_more": true
}

GET /api/v1/b2b/jobs/bulk/{bulk_id}/results

GET

/api/v1/b2b/jobs/bulk/{bulk_id}/results

Get per-item results preview for a bulk submission (B2B enterprise only)

Parameters

Name	Type	Required	Description
bulk_id	`string`	Required	bulk_id
page	`integer`	Optional	Page number (1-indexed).Default: `1`
page_size	`integer`	Optional	Number of results per page (max 50).Default: `20`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/jobs/bulk/<bulk_id>/results \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "bulk_id": "example",
  "total": 0,
  "page": 0,
  "page_size": 0,
  "items": [],
  "summary": "example"
}

GET /api/v1/b2b/jobs/bulk/{bulk_id}/results/download.csv

GET

/api/v1/b2b/jobs/bulk/{bulk_id}/results/download.csv

Download a CSV summary of results for a bulk submission (B2B enterprise only)

Parameters

Name	Type	Required	Description
bulk_id	`string`	Required	bulk_id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/jobs/bulk/<bulk_id>/results/download.csv \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/b2b/jobs/bulk/{bulk_id}/results/download.jsonl

GET

/api/v1/b2b/jobs/bulk/{bulk_id}/results/download.jsonl

Download full, untruncated JSONL results for a bulk submission (B2B enterprise only)

Parameters

Name	Type	Required	Description
bulk_id	`string`	Required	bulk_id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/jobs/bulk/<bulk_id>/results/download.jsonl \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/b2b/notification-prefs

GET

/api/v1/b2b/notification-prefs

Get notification preferences (enterprise tenant self-service)

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/notification-prefs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "tenant_id": "example",
  "prefs": [],
  "total": 0
}

PATCH /api/v1/b2b/notification-prefs

PATCH

/api/v1/b2b/notification-prefs

Update notification preferences (enterprise tenant self-service)

Parameters

Name	Type	Required	Description
prefs	`object[]`	Required	List of preference updates. Each item is upserted individually.

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/b2b/notification-prefs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prefs": []
  }'

Response Example

JSON

{
  "tenant_id": "example",
  "prefs": [],
  "total": 0,
  "upserted": 0
}

GET /api/v1/b2b/onboarding

GET

/api/v1/b2b/onboarding

Enterprise onboarding journey

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/onboarding \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "steps": [],
  "next_step": "example",
  "all_complete": true
}

POST /api/v1/b2b/onboarding/steps/{step_key}/refresh

POST

/api/v1/b2b/onboarding/steps/{step_key}/refresh

Re-check one onboarding step

Parameters

Name	Type	Required	Description
step_key	`string`	Required	step_key
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/b2b/onboarding/steps/<step_key>/refresh \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "steps": [],
  "next_step": "example",
  "all_complete": true
}

GET /api/v1/b2b/overview

GET

/api/v1/b2b/overview

Enterprise client portal overview

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/overview \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "client": "example",
  "acceptance": [],
  "delivery": "example",
  "readiness": "example"
}

GET /api/v1/b2b/package

GET

/api/v1/b2b/package

Dashboard package for the caller's enterprise organization

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/package \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "label": "example",
  "modules": [],
  "labels": {},
  "kpis": [],
  "workflow_entry_points": []
}

GET /api/v1/b2b/profiles

GET

/api/v1/b2b/profiles

List demographic profiles for the calling org (B2B enterprise tenants only)

Parameters

Name	Type	Required	Description
status	`"building" \| "complete" \| "failed"`	Optional	Optional filter by profile build status. Accepted values: 'building', 'complete', 'failed'. When omitted, all statuses are returned.
limit	`integer`	Optional	Maximum number of profiles to return (1–1000). Default: 100.Default: `100`
offset	`integer`	Optional	Number of profiles to skip before returning results. Default: 0.Default: `0`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/profiles \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": [],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "has_more": true
}

GET /api/v1/b2b/profiles/{profile_id}/stats

GET

/api/v1/b2b/profiles/{profile_id}/stats

Per-profile ad-performance stats (B2B enterprise tenants only)

Parameters

Name	Type	Required	Description
profile_id	`string`	Required	Profile ID returned by POST /api/v1/b2b/profiles.
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/profiles/<profile_id>/stats \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "profile_id": "example",
  "total_queries": 0,
  "total_ads": 0,
  "demographic_ads": 0,
  "demographic_ad_rate": 0,
  "last_used_at": "example"
}

GET /api/v1/b2b/tenants/{tenant_id}/config

GET

/api/v1/b2b/tenants/{tenant_id}/config

Read tenant config (B2B API key — enterprise only)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/config \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "rate_limit_override": "example",
  "default_country": "example",
  "delivery_config": "example",
  "mfa_required": true,
  "api_key_audit_enabled": true
}

POST /api/v1/b2b/tenants/{tenant_id}/delivery-configs

POST

/api/v1/b2b/tenants/{tenant_id}/delivery-configs

Create a delivery config (B2B API key — enterprise tenants only)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
X-Organization-Id	`string`	Optional	X-Organization-Id
delivery_type	`"s3" \| "webhook" \| "polling" \| "batch_export"`	Required	Supported delivery methods for tenant data output.
credentials	`object`	Required	Delivery credentials (encrypted at rest). s3: {{access_key_id, secret_access_key}}. webhook: {{signing_secret}} (optional). polling/batch_export: {{}} (no credentials required).
config_json	`object`	Optional	Non-secret delivery configuration. s3: {{prefix, format, bucket}}. webhook: {{endpoint, events, headers}}. polling: {{format, retention_hours}}. batch_export: {{format, schedule}}.
freshness_target_seconds	`integer`	Optional	Maximum acceptable data age in seconds (60s–7d). Default: 86400 (24h).Default: `86400`
retry_policy_json	`object`	Optional	Retry policy. Example: {{"max_attempts": 3, "backoff_seconds": [30, 120, 600]}}
is_active	`boolean`	Optional	Whether this config is activeDefault: `True`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_type": "...",
    "credentials": "...",
    "freshness_target_seconds": 86400
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/b2b/tenants/{tenant_id}/delivery-configs

GET

/api/v1/b2b/tenants/{tenant_id}/delivery-configs

List delivery configs for the caller's org (B2B API key)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
include_inactive	`boolean`	Optional	Include inactive configs; only active ones are listed when omittedDefault: `False`
limit	`integer`	Optional	Maximum number of configs to returnDefault: `100`
offset	`integer`	Optional	Number of configs to skip (for pagination)Default: `0`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "configs": [],
  "total_count": 0,
  "limit": 0,
  "offset": 0,
  "has_more": true
}

PATCH /api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}

PATCH

/api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}

Update non-credential fields of a delivery config (B2B API key)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
config_id	`string`	Required	Delivery config UUID
X-Organization-Id	`string`	Optional	X-Organization-Id
config_json	`object`	Optional	config_json
freshness_target_seconds	`integer`	Optional	freshness_target_seconds
retry_policy_json	`object`	Optional	retry_policy_json
is_active	`boolean`	Optional	is_active

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs/<config_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "tenant_id": "example",
  "delivery_type": "example",
  "config_json": {},
  "freshness_target_seconds": 0,
  "retry_policy_json": {}
}

GET /api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}

GET

/api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}

Get a specific delivery config for the caller's org (B2B API key)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
config_id	`string`	Required	Delivery config UUID

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs/<config_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "tenant_id": "example",
  "delivery_type": "example",
  "config_json": {},
  "freshness_target_seconds": 0,
  "retry_policy_json": {}
}

POST /api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}/rotate

POST

/api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}/rotate

Rotate (replace) delivery credentials without downtime (B2B API key)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
config_id	`string`	Required	Delivery config UUID
X-Organization-Id	`string`	Optional	X-Organization-Id
credentials	`object`	Required	New credentials to replace the existing ones

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs/<config_id>/rotate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": "..."
  }'

Response Example

JSON

{
  "id": "example",
  "tenant_id": "example",
  "delivery_type": "example",
  "config_json": {},
  "freshness_target_seconds": 0,
  "retry_policy_json": {}
}

POST /api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}/test

POST

/api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}/test

Test a delivery config connection (B2B API key — enterprise tenants only)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
config_id	`string`	Required	Delivery config UUID

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs/<config_id>/test \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "success": true,
  "message": "example",
  "delivery_type": "example"
}

GET /api/v1/b2b/usage

GET

/api/v1/b2b/usage

B2B org-scoped billing-period usage aggregator

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/usage \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "billing_period": "example",
  "queries_used": 0,
  "queries_limit": 0,
  "ad_fill_rate": "example",
  "avg_ads_per_query": "example",
  "demographic_ad_rate": "example"
}

Last updated: June 2026

API Reference

Auto-generated

B2B

API reference for b2b endpoints.

Auto-generated

This page was generated from the OpenAPI spec. Runmake generate-docs to refresh after spec changes.

GET /api/v1/b2b/deliveries

GET

/api/v1/b2b/deliveries

Get delivery history (B2B enterprise tenants only)

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	Page size — number of receipts to return (1–200, default 50).Default: `50`
offset	`integer`	Optional	0-based row offset for pagination (default 0).Default: `0`
status	`"success" \| "failure"`	Optional	Optional filter by delivery outcome. Accepted values: 'success', 'failure'. When omitted, all statuses are returned.
delivery_type	`"s3" \| "webhook" \| "polling" \| "batch_export"`	Optional	Optional filter by delivery method. Accepted values: 's3', 'webhook', 'polling', 'batch_export'. When omitted, all delivery types are returned.
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/deliveries \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": [],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "filters": {}
}

GET /api/v1/b2b/health

GET

/api/v1/b2b/health

B2B org-scoped health aggregator

Parameters

Name	Type	Required	Description
window	`"24h" \| "7d" \| "30d"`	Optional	Aggregation window: '24h' (last 24 hours), '7d' (last 7 days), '30d' (last 30 days).Default: `24h`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/health \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "window": "example",
  "ad_fill_rate": "example",
  "ad_fill_rate_jobs": "example",
  "serp_success_rate": "example",
  "serp_success_rate_jobs": "example",
  "delivery_success_rate": "example"
}

GET /api/v1/b2b/jobs

GET

/api/v1/b2b/jobs

List bulk submissions (B2B enterprise tenants only)

Parameters

Name	Type	Required	Description
limit	`integer`	Optional	Page size (max 100).Default: `20`
offset	`integer`	Optional	Number of records to skip.Default: `0`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": [],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "has_more": true
}

GET /api/v1/b2b/jobs/bulk/{bulk_id}/results

GET

/api/v1/b2b/jobs/bulk/{bulk_id}/results

Get per-item results preview for a bulk submission (B2B enterprise only)

Parameters

Name	Type	Required	Description
bulk_id	`string`	Required	bulk_id
page	`integer`	Optional	Page number (1-indexed).Default: `1`
page_size	`integer`	Optional	Number of results per page (max 50).Default: `20`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/jobs/bulk/<bulk_id>/results \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "bulk_id": "example",
  "total": 0,
  "page": 0,
  "page_size": 0,
  "items": [],
  "summary": "example"
}

GET /api/v1/b2b/jobs/bulk/{bulk_id}/results/download.csv

GET

/api/v1/b2b/jobs/bulk/{bulk_id}/results/download.csv

Download a CSV summary of results for a bulk submission (B2B enterprise only)

Parameters

Name	Type	Required	Description
bulk_id	`string`	Required	bulk_id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/jobs/bulk/<bulk_id>/results/download.csv \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/b2b/jobs/bulk/{bulk_id}/results/download.jsonl

GET

/api/v1/b2b/jobs/bulk/{bulk_id}/results/download.jsonl

Download full, untruncated JSONL results for a bulk submission (B2B enterprise only)

Parameters

Name	Type	Required	Description
bulk_id	`string`	Required	bulk_id
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/jobs/bulk/<bulk_id>/results/download.jsonl \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/b2b/notification-prefs

GET

/api/v1/b2b/notification-prefs

Get notification preferences (enterprise tenant self-service)

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/notification-prefs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "tenant_id": "example",
  "prefs": [],
  "total": 0
}

PATCH /api/v1/b2b/notification-prefs

PATCH

/api/v1/b2b/notification-prefs

Update notification preferences (enterprise tenant self-service)

Parameters

Name	Type	Required	Description
prefs	`object[]`	Required	List of preference updates. Each item is upserted individually.

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/b2b/notification-prefs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prefs": []
  }'

Response Example

JSON

{
  "tenant_id": "example",
  "prefs": [],
  "total": 0,
  "upserted": 0
}

GET /api/v1/b2b/onboarding

GET

/api/v1/b2b/onboarding

Enterprise onboarding journey

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/onboarding \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "steps": [],
  "next_step": "example",
  "all_complete": true
}

POST /api/v1/b2b/onboarding/steps/{step_key}/refresh

POST

/api/v1/b2b/onboarding/steps/{step_key}/refresh

Re-check one onboarding step

Parameters

Name	Type	Required	Description
step_key	`string`	Required	step_key
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/b2b/onboarding/steps/<step_key>/refresh \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "steps": [],
  "next_step": "example",
  "all_complete": true
}

GET /api/v1/b2b/overview

GET

/api/v1/b2b/overview

Enterprise client portal overview

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/overview \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "client": "example",
  "acceptance": [],
  "delivery": "example",
  "readiness": "example"
}

GET /api/v1/b2b/package

GET

/api/v1/b2b/package

Dashboard package for the caller's enterprise organization

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/package \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "label": "example",
  "modules": [],
  "labels": {},
  "kpis": [],
  "workflow_entry_points": []
}

GET /api/v1/b2b/profiles

GET

/api/v1/b2b/profiles

List demographic profiles for the calling org (B2B enterprise tenants only)

Parameters

Name	Type	Required	Description
status	`"building" \| "complete" \| "failed"`	Optional	Optional filter by profile build status. Accepted values: 'building', 'complete', 'failed'. When omitted, all statuses are returned.
limit	`integer`	Optional	Maximum number of profiles to return (1–1000). Default: 100.Default: `100`
offset	`integer`	Optional	Number of profiles to skip before returning results. Default: 0.Default: `0`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/profiles \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "items": [],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "has_more": true
}

GET /api/v1/b2b/profiles/{profile_id}/stats

GET

/api/v1/b2b/profiles/{profile_id}/stats

Per-profile ad-performance stats (B2B enterprise tenants only)

Parameters

Name	Type	Required	Description
profile_id	`string`	Required	Profile ID returned by POST /api/v1/b2b/profiles.
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/profiles/<profile_id>/stats \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "profile_id": "example",
  "total_queries": 0,
  "total_ads": 0,
  "demographic_ads": 0,
  "demographic_ad_rate": 0,
  "last_used_at": "example"
}

GET /api/v1/b2b/tenants/{tenant_id}/config

GET

/api/v1/b2b/tenants/{tenant_id}/config

Read tenant config (B2B API key — enterprise only)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/config \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "rate_limit_override": "example",
  "default_country": "example",
  "delivery_config": "example",
  "mfa_required": true,
  "api_key_audit_enabled": true
}

POST /api/v1/b2b/tenants/{tenant_id}/delivery-configs

POST

/api/v1/b2b/tenants/{tenant_id}/delivery-configs

Create a delivery config (B2B API key — enterprise tenants only)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
X-Organization-Id	`string`	Optional	X-Organization-Id
delivery_type	`"s3" \| "webhook" \| "polling" \| "batch_export"`	Required	Supported delivery methods for tenant data output.
credentials	`object`	Required	Delivery credentials (encrypted at rest). s3: {{access_key_id, secret_access_key}}. webhook: {{signing_secret}} (optional). polling/batch_export: {{}} (no credentials required).
config_json	`object`	Optional	Non-secret delivery configuration. s3: {{prefix, format, bucket}}. webhook: {{endpoint, events, headers}}. polling: {{format, retention_hours}}. batch_export: {{format, schedule}}.
freshness_target_seconds	`integer`	Optional	Maximum acceptable data age in seconds (60s–7d). Default: 86400 (24h).Default: `86400`
retry_policy_json	`object`	Optional	Retry policy. Example: {{"max_attempts": 3, "backoff_seconds": [30, 120, 600]}}
is_active	`boolean`	Optional	Whether this config is activeDefault: `True`

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_type": "...",
    "credentials": "...",
    "freshness_target_seconds": 86400
  }'

Response Example

JSON

{
  "status": "ok"
}

GET /api/v1/b2b/tenants/{tenant_id}/delivery-configs

GET

/api/v1/b2b/tenants/{tenant_id}/delivery-configs

List delivery configs for the caller's org (B2B API key)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
include_inactive	`boolean`	Optional	Include inactive configs; only active ones are listed when omittedDefault: `False`
limit	`integer`	Optional	Maximum number of configs to returnDefault: `100`
offset	`integer`	Optional	Number of configs to skip (for pagination)Default: `0`
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "configs": [],
  "total_count": 0,
  "limit": 0,
  "offset": 0,
  "has_more": true
}

PATCH /api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}

PATCH

/api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}

Update non-credential fields of a delivery config (B2B API key)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
config_id	`string`	Required	Delivery config UUID
X-Organization-Id	`string`	Optional	X-Organization-Id
config_json	`object`	Optional	config_json
freshness_target_seconds	`integer`	Optional	freshness_target_seconds
retry_policy_json	`object`	Optional	retry_policy_json
is_active	`boolean`	Optional	is_active

Request Example

Bash

curl -X PATCH https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs/<config_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "tenant_id": "example",
  "delivery_type": "example",
  "config_json": {},
  "freshness_target_seconds": 0,
  "retry_policy_json": {}
}

GET /api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}

GET

/api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}

Get a specific delivery config for the caller's org (B2B API key)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
config_id	`string`	Required	Delivery config UUID

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs/<config_id> \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "id": "example",
  "tenant_id": "example",
  "delivery_type": "example",
  "config_json": {},
  "freshness_target_seconds": 0,
  "retry_policy_json": {}
}

POST /api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}/rotate

POST

/api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}/rotate

Rotate (replace) delivery credentials without downtime (B2B API key)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
config_id	`string`	Required	Delivery config UUID
X-Organization-Id	`string`	Optional	X-Organization-Id
credentials	`object`	Required	New credentials to replace the existing ones

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs/<config_id>/rotate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": "..."
  }'

Response Example

JSON

{
  "id": "example",
  "tenant_id": "example",
  "delivery_type": "example",
  "config_json": {},
  "freshness_target_seconds": 0,
  "retry_policy_json": {}
}

POST /api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}/test

POST

/api/v1/b2b/tenants/{tenant_id}/delivery-configs/{config_id}/test

Test a delivery config connection (B2B API key — enterprise tenants only)

Parameters

Name	Type	Required	Description
tenant_id	`string`	Required	Organization (tenant) UUID
config_id	`string`	Required	Delivery config UUID

Request Example

Bash

curl -X POST https://api.alterlab.io/api/v1/b2b/tenants/<tenant_id>/delivery-configs/<config_id>/test \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "success": true,
  "message": "example",
  "delivery_type": "example"
}

GET /api/v1/b2b/usage

GET

/api/v1/b2b/usage

B2B org-scoped billing-period usage aggregator

Parameters

Name	Type	Required	Description
X-Organization-Id	`string`	Optional	X-Organization-Id

Request Example

Bash

curl -X GET https://api.alterlab.io/api/v1/b2b/usage \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Example

JSON

{
  "billing_period": "example",
  "queries_used": 0,
  "queries_limit": 0,
  "ad_fill_rate": "example",
  "avg_ads_per_query": "example",
  "demographic_ad_rate": "example"
}

Last updated: June 2026