Skip to main content
All graph generation endpoints are asynchronous. When you submit a request, the API creates a background job and returns immediately with a job status. You then poll for results by re-submitting the same request with the same Idempotency-Key.

How It Works

Job Statuses

Response Envelope

All graph endpoints return a consistent envelope:
  • status - Current job state
  • jobId - Unique identifier for the job
  • retryAfter - Recommended seconds to wait before the next poll (only present for pending/processing)
  • result - The graph data (only present when completed)
  • error - Error description (only present when failed)

Polling with cURL

Store the Idempotency-Key in a variable and re-use it for polling:
The server uses the Idempotency-Key to identify your existing job. Re-submitting the file does not create a duplicate job.

Using the SDK

The @supermodeltools/sdk package handles polling automatically. Install it with:

Basic Usage

Configuring Polling Behavior

Available Methods

Error Handling

If a job fails, the response will have status: "failed" with an error message:
Common failure reasons:
Jobs have a limited processing window. If a job stays in pending status too long, the uploaded file may expire and the job will be marked as failed.

Idempotency Key Behavior

The Idempotency-Key scopes a job to your API key. Key behaviors:
  • Same key, same user: Returns the existing job (no duplicate processing)
  • Same key, different user: Creates independent jobs (no conflict)
  • New key, same file: Creates a new job (useful for re-analysis after code changes)
Completed jobs are retained for 24 hours. After that, submitting the same idempotency key will create a new job.