Cortex scoring and signature builds are asynchronous. A create request accepts work and returns identifiers. The result becomes available after the job finishes.
Job identifiers
Most async API responses include:
job_id: the async job identifier.scoring_idorsignature_id: the product object created by that job.
Store both. Use product IDs for user-facing links and reporting. Use job IDs for lifecycle tracking if your integration subscribes to completion events.
Completion model
A scoring can finish as:
- Succeeded: numeric scores and narrative/artifacts completed.
- Succeeded partial: numeric scores completed, but a secondary artifact was unavailable.
- Failed: the job did not complete.
Partial success is not a failure for numeric decisioning. Treat the missing artifact as unavailable and use the completed scores.
Customer webhooks
For customer integrations, use a receive endpoint in your system that records Cortex events and then fetches or links to the result. A typical event shape is:
{
"type": "scoring.completed",
"workspace_id": "workspace_123",
"brand_id": "brand_123",
"scoring_id": "scoring_123",
"job_id": "job_123",
"status": "succeeded",
"created_at": "2026-05-25T22:00:00Z"
}
If your workspace has webhook delivery enabled, Cortex signs deliveries and retries transient failures. Keep your endpoint idempotent: receiving the same event twice should not create duplicate downstream work.
Polling fallback
If webhook delivery is not enabled for your workspace, use polling around the app result or your stored job IDs. Poll with backoff and stop after a terminal status.
Recommended polling behavior:
- Start with a 2 to 5 second delay.
- Increase gradually for long-running jobs.
- Stop when status is succeeded, succeeded partial, or failed.
- Do not poll faster than the API rate limits.
What not to infer
Do not assume a missing heatmap or narrative means the score failed. Check the scoring state first. A successful or partial scoring can still be useful when a secondary artifact is absent.
Do not create your own duplicate scoring when a job is slow. Retry the original create request only with the same Idempotency-Key, or wait for completion.