Poll status guide

For live updates without polling, subscribe to the submission’s channel — see the Realtime updates guide. Polling remains the reliable fallback and the way to reconcile state.

Status polling pattern

The typical polling flow looks like this:

Create submission

POST to create a submission and read the submissionId.

Poll status

GET the submission at regular intervals.

Check completion

When the submission is complete, partial, or failed, stop polling. queued and processing are both non-terminal — keep polling through them.

Retrieve results

Fetch each asset’s result and its issues or clustered topics.

Getting submission status

Use GET /api/submissions/{submission_id} — there is no /status suffix.

curl -H "X-API-Key: your-api-key-here" \
  https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions/550e8400-e29b-41d4-a716-446655440000

import requests

API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations"
submission_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    f"{API_BASE}/api/submissions/{submission_id}",
    headers={"X-API-Key": "your-api-key-here"},
)

status = response.json()
print(f"Submission status: {status['status']} ({status['progressPercent']}%)")
for asset in status["assets"]:
    print(f"  {asset['assetId']}: issues={asset['issueCount']}")

const API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations";
const submissionId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(
  `${API_BASE}/api/submissions/${submissionId}`,
  {
    headers: { "X-API-Key": "your-api-key-here" },
  }
);

const status = await response.json();
console.log(`Submission status: ${status.status} (${status.progressPercent}%)`);
status.assets.forEach((asset) => {
  console.log(`  ${asset.assetId}: issues=${asset.issueCount}`);
});

Response:

{
  "submissionId": "550e8400-...",
  "workflowId": null,
  "workspaceId": "660e8400-...",
  "status": "processing",
  "progressPercent": 40,
  "createdAt": "2026-06-03T12:00:00Z",
  "startedAt": "2026-06-03T12:00:05Z",
  "completedAt": null,
  "errorMessage": null,
  "assets": [
    {
      "assetId": "a1b2...",
      "versionGroupId": "g1...",
      "versionNumber": 1,
      "issueCount": null,
      "errorMessage": null,
      "errorType": null,
      "isRetryable": false,
      "retryCount": 0,
      "workflowId": "asset-review-...",
      "startedAt": "2026-06-03T12:00:05Z",
      "completedAt": null
    }
  ],
  "isRetryable": false
}

Per-asset failures are reported as flat fields — errorMessage, errorType, isRetryable, retryCount — not a nested error object. The terminal submission statuses are complete, partial, and failed. A queued status means every asset is accepted and waiting for a free review slot — it is non-terminal, so keep polling. Assets are admitted to review a few at a time, so don’t infer progress from the submission status alone: it reads processing as soon as the first asset starts and stays there until the last one settles. Read assets[].processingStatus to see which assets are still queued versus already compliant / in_review / failed. startedAt and completedAt report when work actually happened, so completedAt - startedAt is the real processing time. Both are per attempt: they sit at null while an asset waits in the queue, and a retry re-stamps startedAt and clears completedAt. completedAt is set for any terminal outcome, so on a failed asset it is the failure time rather than a success time. At the submission level, startedAt is the earliest asset start.

Polling strategy

Basic polling loop

import time
import requests

API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations"

def wait_for_completion(
    submission_id: str,
    api_key: str,
    max_wait_seconds: int = 300,
    poll_interval: int = 5,
) -> dict:
    """Poll until the submission reaches a terminal state."""

    start_time = time.time()

    while time.time() - start_time < max_wait_seconds:
        response = requests.get(
            f"{API_BASE}/api/submissions/{submission_id}",
            headers={"X-API-Key": api_key},
        )
        status = response.json()

        if status["status"] in ("complete", "partial", "failed"):
            return status

        print(f"Status: {status['status']}, waiting {poll_interval}s...")
        time.sleep(poll_interval)

    raise TimeoutError(
        f"Submission did not finish within {max_wait_seconds} seconds"
    )

# Usage
status = wait_for_completion(
    "550e8400-e29b-41d4-a716-446655440000", "your-api-key-here"
)
print(f"Final status: {status['status']}")

const API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations";

async function waitForCompletion(
  submissionId,
  apiKey,
  maxWaitSeconds = 300,
  pollInterval = 5000
) {
  const startTime = Date.now();

  while (Date.now() - startTime < maxWaitSeconds * 1000) {
    const response = await fetch(
      `${API_BASE}/api/submissions/${submissionId}`,
      { headers: { "X-API-Key": apiKey } }
    );
    const status = await response.json();

    if (
      status.status === "complete" ||
      status.status === "partial" ||
      status.status === "failed"
    ) {
      return status;
    }

    console.log(`Status: ${status.status}, waiting ${pollInterval}ms...`);
    await new Promise((resolve) => setTimeout(resolve, pollInterval));
  }

  throw new Error(
    `Submission did not finish within ${maxWaitSeconds} seconds`
  );
}

// Usage
const status = await waitForCompletion(
  "550e8400-e29b-41d4-a716-446655440000",
  "your-api-key-here"
);
console.log("Final status:", status.status);

Exponential backoff

For long-running submissions, start with short intervals and back off over time:

import time
import requests

API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations"

def wait_with_backoff(
    submission_id: str,
    api_key: str,
    initial_interval: float = 2,
    max_interval: float = 30,
    max_wait_seconds: int = 600,
) -> dict:
    """Poll with exponential backoff until terminal."""

    start_time = time.time()
    current_interval = initial_interval

    while time.time() - start_time < max_wait_seconds:
        response = requests.get(
            f"{API_BASE}/api/submissions/{submission_id}",
            headers={"X-API-Key": api_key},
        )
        status = response.json()

        if status["status"] in ("complete", "partial", "failed"):
            return status

        time.sleep(current_interval)
        current_interval = min(current_interval * 1.5, max_interval)

    raise TimeoutError(
        f"Submission did not finish within {max_wait_seconds} seconds"
    )

Retrieving results

Once an asset is done, fetch its result with GET /api/submissions/{submission_id}/assets/{asset_id}. The result includes the asset’s status, issueCount, and an issues array. For the flat enriched issue list call .../assets/{asset_id}/issues; for AI-clustered topics call .../assets/{asset_id}/topics.

curl -H "X-API-Key: your-api-key-here" \
  https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions/550e8400-.../assets/a1b2.../issues

import requests

API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations"
submission_id = "550e8400-e29b-41d4-a716-446655440000"
asset_id = "a1b2..."

# Asset result (includes status, issueCount, and inline issues)
result = requests.get(
    f"{API_BASE}/api/submissions/{submission_id}/assets/{asset_id}",
    headers={"X-API-Key": "your-api-key-here"},
).json()
print(f"Status: {result['status']}, issues: {result['issueCount']}")
for issue in result["issues"]:
    print(f"  [{issue['severity']}] {issue['ruleCode']}: {issue['summary']}")

# Or the flat enriched issue list
issues = requests.get(
    f"{API_BASE}/api/submissions/{submission_id}/assets/{asset_id}/issues",
    headers={"X-API-Key": "your-api-key-here"},
).json()
print(f"Total issues: {issues['total']}")

Asset result shape:

{
  "assetId": "a1...",
  "submissionId": "s1...",
  "filename": "campaign-video.mp4",
  "mimeType": "video/mp4",
  "status": "complete",
  "issueCount": 2,
  "versionNumber": 1,
  "versionGroupId": "g1...",
  "startedAt": "2026-06-03T12:00:05Z",
  "completedAt": "2026-06-03T12:04:12Z",
  "issues": [
    {
      "id": "i1...",
      "referenceNumber": 1,
      "ruleCode": "CAP_8.4",
      "summary": "Unsubstantiated pricing claim",
      "severity": "MAJOR",
      "status": "OPEN"
    }
  ]
}

Issue severity is one of CRITICAL | MAJOR | MINOR | INFO, and issue status is one of OPEN | ACKNOWLEDGED | AWAITING_HUMAN_INPUT | RESOLVED | DISMISSED. The clustered topics endpoint returns { "assetId", "topics", "orphanIssues", "metadata" }. Topics group two or more related issues; orphanIssues are unclustered singletons and are normal. The issues and topics endpoints return 404 if the asset has not finished processing yet.

Complete polling example

A full end-to-end example:

import requests
import time

API_KEY = "your-api-key-here"
API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations"

def submit_and_wait(file_paths: list[str]) -> list[dict]:
    """Upload files, submit, wait for completion, and return results."""

    # Step 1: Upload files via presigned URLs and collect assets
    assets = []
    for file_path in file_paths:
        # Request a presigned URL, then PUT the bytes straight to Azure
        url_resp = requests.post(
            f"{API_BASE}/api/uploads/url",
            headers={"X-API-Key": API_KEY},
            json={"filename": file_path.split("/")[-1], "contentType": "video/mp4"},
        )
        url_resp.raise_for_status()
        data = url_resp.json()
        with open(file_path, "rb") as f:
            requests.put(
                data["uploadUrl"],
                headers={"x-ms-blob-type": "BlockBlob"},
                data=f,
            ).raise_for_status()
        assets.append({"blobPath": data["blobPath"]})

    # Create the submission
    submission = requests.post(
        f"{API_BASE}/api/submissions",
        headers={"X-API-Key": API_KEY},
        json={"assets": assets, "sidekickIds": ["<sidekick-id>"]},
    ).json()
    submission_id = submission["submissionId"]
    print(f"Created submission: {submission_id}")

    # Step 2: Poll until terminal
    status = {}
    start_time = time.time()
    while time.time() - start_time < 600:
        status = requests.get(
            f"{API_BASE}/api/submissions/{submission_id}",
            headers={"X-API-Key": API_KEY},
        ).json()
        print(f"  status={status['status']} progress={status['progressPercent']}%")
        if status["status"] in ("complete", "partial", "failed"):
            break
        time.sleep(5)

    # Step 3: Retrieve each asset's result
    results = []
    for asset in status["assets"]:
        result = requests.get(
            f"{API_BASE}/api/submissions/{submission_id}"
            f"/assets/{asset['assetId']}",
            headers={"X-API-Key": API_KEY},
        ).json()
        if result["status"] == "complete":
            results.append(result)

    print(f"Completed processing {len(results)} assets")
    return results

# Usage
results = submit_and_wait(["video1.mp4", "video2.mp4"])
for result in results:
    print(f"\n{result['filename']}: {result['issueCount']} issues")
    for issue in result["issues"]:
        print(f"  [{issue['severity']}] {issue['summary']}")

Polling recommendations

Start with a poll interval of a few seconds for fast feedback.
Back off over time to avoid hammering the API.
Use progressPercent to surface progress to your users.
Set a reasonable timeout to prevent infinite waits.
Prefer webhooks over tight polling for production volume.

Polling vs webhooks

Factor	Polling	Webhooks
Latency	Delayed by poll interval	Real-time
Complexity	Simpler to implement	Requires an endpoint
Throughput	Better for few submissions	Better for many
Load	Higher on the API	Lower on the API

For production systems with high volume, webhooks are recommended. See Webhook subscriptions.

Handling timeouts

If a submission does not finish within your timeout:

Re-fetch the submission later — it may simply still be processing.
Check the per-asset errorMessage, errorType, and isRetryable fields.
Retry a failed, retryable asset with POST .../assets/{asset_id}/retry.
Switch to webhooks for more reliable completion detection.

Getting Started

Core Concepts

Guides

Reference

API Endpoints

Status polling pattern

Getting submission status

Polling strategy

Basic polling loop

Exponential backoff

Retrieving results

Complete polling example

Polling recommendations

Polling vs webhooks

Handling timeouts

​Status polling pattern

​Getting submission status

​Polling strategy

​Basic polling loop

​Exponential backoff

​Retrieving results

​Complete polling example

​Polling recommendations

​Polling vs webhooks

​Handling timeouts

Status polling pattern

Getting submission status

Polling strategy

Basic polling loop

Exponential backoff

Retrieving results

Complete polling example

Polling recommendations

Polling vs webhooks

Handling timeouts