> ## Documentation Index
> Fetch the complete documentation index at: https://docs.identifai.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Deferred Results

> Some results of a submission, such as the textual explanations of the XAI maps and of the heatmap, are produced after the main results. Learn how to track them and how to be notified when they are complete.

# Deferred Results

The analysis of a submission has two phases:

1. the **main analysis** produces the verdict and the classification results. When it ends, the submission `status` becomes `done` (or `errored`) and the main results are sent to `webhook_url` and to your webhooks, as before;
2. the **deferred results** are produced afterwards, without delaying the main results. Today they are the AI-powered explanations of the XAI maps and of the heatmap, requested with `with_xai` and `with_llm_xai` (see [XAI – eXplainable AI](https://docs.identifai.net/classification/classify-image.md#xai-explainable-ai)) and returned in the `description` of the `explanations` of the per-model results.

The deferred results never change the verdict, the classification results or the `status` of the submission.

## Tracking the deferred results

When a submission has deferred results, the classification result (`GET /api/classification/{identifier}`, `GET /api/classification_video/{identifier}`, `GET /api/classification_audio/{identifier}`) also contains:

| Field | Description |
| - | - |
| `deferred_status` | `pending` (main analysis still running), `inprogress`, `done`, `errored` (at least one deferred step failed: the main results are still valid), `skipped` (the main analysis failed), `expired` (not completed in time) |
| `deferred_progress` | `{ "current_idx": 1, "total": 2 }`: deferred steps completed so far, out of the total |
| `deferred_errors` | Public messages of the deferred steps that failed |

For videos, every analyzed frame in `results.images` has its own `deferred_status`. The fields are missing for submissions without deferred results.

> [!NOTE]
>
> `expired` is not final: if the deferred results complete after the deadline, `deferred_status` becomes `done` or `errored`.

> [!NOTE]
>
> `errored` does not mean that no explanation is available. When some explanations of the XAI maps or of the heatmap cannot be generated because of a technical error, `deferred_status` is `errored` and `deferred_errors` contains `Some explanations of the XAI maps could not be generated`, while the explanations generated for the other maps are still returned in `explanations`. The maps without an explanation stay in `explanations` with `description` set to `null`; a map the model cannot describe also has `description` `null`, and is not an error.

## Deferred results notification

To be notified when the deferred results are complete, set `deferred_webhook_url` when you submit an image, a video or a speech (also from URL). It works like `webhook_url`: it needs the same enablement and has the same domain restrictions and authentication. If it is omitted or empty, no notification is sent.

You can also enable the notification on the webhooks configured in the dashboard, with **Notify deferred results** and an optional dedicated URL. The notification is sent only to the webhooks that received the main result of the submission: for example, a webhook that only notifies artificial results gets no deferred notification for a human result.

The notification is sent **once**, when the deferred results become `done`, `errored` or `expired`: it is not sent for the single steps, nor when the main analysis failed (`skipped`). For a video, it is sent after the last frame.

```json theme={null}
{
  "event": "submission.deferred.completed",
  "version": 1,
  "sent_at": "2026-10-27T12:00:00.000Z",
  "submission": {
    "identifier": "8f0c2d3e9b1a4c7d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5",
    "type": "image",
    "status": "done",
    "deferred_status": "done",
    "deferred_progress": { "current_idx": 1, "total": 1 },
    "completed_at": "2026-10-27T11:58:41.000Z",
    "deferred_completed_at": "2026-10-27T11:59:58.000Z",
    "deferred_errors": [],
    "xai": [
      {
        "model": "...",
        "method": "legrad",
        "type": "attention_map",
        "artifact": "...",
        "description": "The model focuses on the skin texture around the eyes and on the hairline, where the generated details are less consistent."
      }
    ],
    "heatmaps": [
      {
        "model": "...",
        "artifact": "...",
        "description": "The highlighted area around the mouth shows signs of manipulation."
      }
    ],
    "frames": []
  }
}
```

| Field | Description |
| - | - |
| `event` | Always `submission.deferred.completed` |
| `version` | Version of the payload, incremented on breaking changes |
| `sent_at` | When the notification was sent |
| `submission.identifier` | The same `identifier` returned on submission and sent in the main notification |
| `submission.type` | `image`, `audio` or `video` |
| `submission.status` | Status of the main analysis |
| `submission.deferred_status` | `done`, `errored` or `expired` |
| `submission.deferred_errors` | Public messages of the deferred steps that failed |
| `submission.xai` | Textual explanations of the XAI maps |
| `submission.heatmaps` | Textual explanations of the heatmaps |
| `submission.frames` | Videos only: `hash`, `name`, `status`, `deferred_status`, `xai` and `heatmaps` of every frame |

> [!WARNING]
>
> Delivery is **at least once**: the same notification can arrive more than once, so deduplicate it by `identifier` and `deferred_status`. An `expired` notification can be followed by a second notification with the real outcome (`done` or `errored`): the later one supersedes the earlier one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.