# Temps réel et asynchrone

Recevez les résultats dans la réponse ou soumettez une tâche pour les récupérer plus tard. Choisissez comment votre application ou votre agent attend le traitement.

Référence canonique : https://flashdata.dev/fr/docs/reference/realtime-and-async
Vérifié le 2026-11-04 par FlashData

<a id="choose"></a>

## Choisir un mode de requête

Google Search et YouTube Data acceptent les deux modes. YouTube Download nécessite async, Batch ou Bulk ; realtime n’est pas pris en charge. Les paramètres de la source restent identiques lorsque vous passez de realtime à async.

| Mode | Quand l’utiliser | Ce que vous recevez |
| --- | --- | --- |
| Realtime | Le résultat de recherche est nécessaire pendant l’interaction en cours. | Le corps du résultat dans la même réponse HTTP. |
| Async | Le traitement doit continuer après la déconnexion de votre processus, ou vous téléchargez des médias. | Un identifiant de tâche immédiatement ; l’état et les résultats se récupèrent séparément. |

### Cycle de vie d’une requête

```text
Realtime  POST data.flashdata.dev/v1/queries/realtime → résultats
Async     POST data.flashdata.dev/v1/queries          → identifiant de tâche
          GET  api.flashdata.dev/v2/jobs/{id}         → état
          GET  api.flashdata.dev/v2/jobs/{id}/results → résultats
```

- [Vous soumettez plusieurs requêtes ?](https://flashdata.dev/fr/docs/reference/batch-and-bulk/reference.md)

<a id="submit"></a>

## Envoyer une requête

Définissez FLASHDATA_API_KEY avec une clé autorisant google_search. Choisissez realtime ou async ; chaque soumission lance une recherche facturable. Conservez les scripts, reçus et résultats dans un même nouveau dossier de travail.

Les exemples Python utilisent Python 3.10+ et Requests. Chaque script s’exécute indépendamment et lit les fichiers enregistrés aux étapes précédentes. L’alternative cURL nécessite Bash, cURL 7.76+ et jq.

### Python · installer une seule fois

```bash
python3 -m pip install requests
```

- [Clé API et en-têtes](https://flashdata.dev/fr/docs/guides/headers-and-authentication/reference.md)
- [Paramètres Google Search](https://flashdata.dev/fr/docs/sources/google_search/reference.md)

<a id="realtime"></a>

### Realtime : recevoir le résultat immédiatement

POST /v1/queries/realtime renvoie status: done et un tableau results. Lisez result.json ; aucun suivi périodique de l’état n’est nécessaire.

#### Python

Enregistrez le fichier sous le nom realtime.py, puis exécutez python3 realtime.py.

##### realtime.py

```python
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=120, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("result.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
```


#### cURL / Bash

##### Obtenir le résultat · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
  --output result.json &&
jq '{source, status, results, usage}' result.json
```



<a id="async"></a>

### Async : enregistrer le reçu de la tâche

POST /v1/queries renvoie un reçu de tâche en attente, pas les résultats de recherche. Enregistrez submission.json, puis utilisez les requêtes d’état et de résultat ci-dessous.

#### Python

Enregistrez le fichier sous le nom submit_async.py, puis exécutez python3 submit_async.py.

##### submit_async.py

```python
import json
import os
from pathlib import Path

import requests

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "google_search", "query": "battery recycling research", "params": {"num": 5}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
result = response.json()
Path("submission.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
print(json.dumps(result, indent=2))
```

##### Champs du reçu · exemple abrégé

```json
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}
```


#### cURL / Bash

##### Soumettre et enregistrer l’identifiant de tâche · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
  --output submission.json &&
jq '{id, source, status, links}' submission.json
```

##### Champs du reçu · exemple abrégé

```json
{
  "id": "job_EXAMPLE",
  "source": "google_search",
  "status": "pending"
}
```



<a id="status"></a>

## Vérifier une tâche asynchrone

Lisez job.status avec l’identifiant de submission.json. Pour pending ou processing, respectez le délai Retry-After avant la prochaine vérification ; Python l’affiche et cURL l’enregistre dans status-headers.txt. Si aucun délai n’est fourni, espacez progressivement les appels. Une requête d’état réussie ne signifie pas que la tâche est terminée.

| job.status | Action suivante |
| --- | --- |
| pending / processing | Attendez, puis vérifiez à nouveau le même identifiant de tâche. |
| completed | Récupérez le résultat enregistré. |
| failed | Lisez job.error. Corrigez la cause avant de soumettre une nouvelle tâche. |

### Python

Enregistrez le fichier sous le nom job_status.py, puis exécutez python3 job_status.py.

#### job_status.py

```python
import json
import os
from pathlib import Path

import requests

job_id = json.loads(Path("submission.json").read_text(encoding="utf-8"))["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
print("Retry-After:", response.headers.get("Retry-After", "not provided"))
```


### cURL / Bash

#### Lire l’état · cURL / Bash

```bash
JOB_ID=$(jq -er '.id' submission.json)
curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/$JOB_ID" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --dump-header status-headers.txt --output job.json &&
jq '.job | {id, source, status, error}' job.json
```



<a id="results"></a>

## Récupérer le résultat d’une tâche terminée

Exécutez cette étape lorsque job.status vaut completed. Par défaut, la réponse des résultats est 302 : Location contient une URL de stockage signée. Les deux requêtes ci-dessous transmettent la clé API uniquement à FlashData et enregistrent le JSON d’origine dans result.json. Pour YouTube Download, ce JSON décrit le média livré dans votre stockage ; il ne contient pas le fichier vidéo ou audio.

### Python

Enregistrez le fichier sous le nom job_result.py, puis exécutez python3 job_result.py.

#### job_result.py

```python
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("submission.json").read_text(encoding="utf-8"))
job_id = receipt["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/jobs/{job_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a result redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

# A separate request: no FlashData key is sent to storage.
result = requests.get(url, timeout=120)
result.raise_for_status()
data = result.json()  # Requests automatically decodes Content-Encoding: gzip.
Path("result.json").write_text(json.dumps(data, indent=2), encoding="utf-8")
print(json.dumps(data, indent=2))
```


### cURL / Bash

#### Récupérer le JSON d’origine · cURL / Bash

```bash
JOB_ID=$(jq -er '.id' submission.json)
RESULT_URL=$(curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/$JOB_ID/results" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --output /dev/null --write-out '%{redirect_url}') &&
curl --fail-with-body --silent --show-error --compressed --proto '=https' \
  "${RESULT_URL:?Expected a signed result URL}" --output result.json &&
jq '{source, status, results, usage}' result.json
```


- [Formats JSON, texte et Markdown](https://flashdata.dev/fr/docs/guides/response-formats/reference.md#completed-results)
- [Configurer le stockage pour Download](https://flashdata.dev/fr/docs/guides/youtube-download-guide/reference.md)

<a id="recovery"></a>

## Gérer les délais et les échecs

| Situation | Action |
| --- | --- |
| Délai d’attente dépassé à la soumission | Un POST a peut-être déjà été accepté. Vérifiez votre reçu enregistré et l’historique du compte avant de le renvoyer ; répéter un POST peut créer de nouvelles tâches facturables. |
| 409 · result_not_ready | Continuez à vérifier l’état périodiquement. Ne créez pas une autre tâche. |
| 422 · result_not_ready | La tâche a échoué. Lisez job.error avant de réessayer. |
| 429 | Respectez Retry-After ou retry_after ; réduisez la fréquence des soumissions lorsque la capacité de tâches en attente est atteinte. |
| 410 · result_expired | Les résultats stockés expirent 24 heures après la fin du traitement. Utilisez votre copie enregistrée. |

- [Erreurs et codes d’état](https://flashdata.dev/fr/docs/errors/reference.md)
- [Guide CLI, suivi périodique et webhook](https://flashdata.dev/fr/docs/guides/async-batch/reference.md)
