Diagnostics

The diagnostic is the fastest way to see what’s in a catalog. You upload a CSV or Excel file, FacetFlux profiles it, and you get back a report: how complete each column is, what product types it found, ETIM readiness, and a few sample enrichments. The first runs per tenant are free. It’s a two-step flow: start a diagnostic (returns immediately with an id), then poll until it’s done and fetch the report.

Start a diagnostic

The upload is a raw-body POST — the request body is the file bytes, not multipart form data. Two headers matter:

Content-Type — send the exact Excel MIME type application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for .xlsx; any other value is treated as CSV.
Content-Disposition — carries the filename, e.g. attachment; filename="catalog.csv".

An optional ?language= query parameter (en or de, default en) sets the report language.

curl -X POST "https://app.facetflux.com/api/v1/diagnostics?language=en" \
  -H "Authorization: Bearer $FACETFLUX_API_KEY" \
  -H "Content-Type: text/csv" \
  -H 'Content-Disposition: attachment; filename="catalog.csv"' \
  --data-binary @catalog.csv

import os, requests

with open("catalog.csv", "rb") as f:
    body = f.read()

resp = requests.post(
    "https://app.facetflux.com/api/v1/diagnostics",
    params={"language": "en"},
    headers={
        "Authorization": f"Bearer {os.environ['FACETFLUX_API_KEY']}",
        "Content-Type": "text/csv",
        "Content-Disposition": 'attachment; filename="catalog.csv"',
    },
    data=body,
)
resp.raise_for_status()
diagnostic_id = resp.json()["id"]

A successful start returns 202 Accepted with { "id": "...", "wasFree": true }. The id identifies the report you’ll poll for.

Only one diagnostic runs per tenant at a time — starting a second while one is active returns 409. Starts are also rate-limited to a few per hour.

Poll for completion

Poll GET /api/v1/diagnostics/{id} until status is completed (or failed):

Python

import time

while True:
    r = requests.get(
        f"https://app.facetflux.com/api/v1/diagnostics/{diagnostic_id}",
        headers={"Authorization": f"Bearer {os.environ['FACETFLUX_API_KEY']}"},
    ).json()
    if r["status"] in ("completed", "failed"):
        break
    print(r["phase"], r.get("progress"))
    time.sleep(2)

The poll response carries status (queued / processing / completed / failed), a human-readable phase, progress, and error if it failed.

Read the report

Once completed, fetch the full report:

curl "https://app.facetflux.com/api/v1/diagnostics/$DIAGNOSTIC_ID/report" \
  -H "Authorization: Bearer $FACETFLUX_API_KEY"

The report is built in phases, so the fields fill in as the analysis progresses:

Profile — averageCompleteness (overall score) and columns, each with a fillRate, rowsWithValue, uniqueValueCount, and topValues.
Understand — typeGroups (the product types it detected, each with its own completeness and per-attribute fill rates), a qualityNarrative, and structured issues.
ETIM readiness — etimReadiness per product type: the matched ETIM class, coverage percentage, and missingFeatures the class expects.
Samples — a few samples showing before values and AI suggestions, so you can see the kind of enrichment FacetFlux would produce.

GET /api/v1/diagnostics returns your ten most recent reports (a bare array, newest first).

Turn gaps into values

The diagnostic shows what’s missing. Enrichment fills it — see the Enrichment guide.

Get started

Guides

AI & agents

Start a diagnostic

Poll for completion

Read the report

Turn gaps into values

​Start a diagnostic

​Poll for completion

​Read the report

Turn gaps into values

Start a diagnostic

Poll for completion

Read the report