# Realtime dan async

Dapatkan hasil dalam respon, atau mengirimkan pekerjaan dan mengambil mereka nanti. Pilih bagaimana aplikasi atau agenmu menunggu untuk bekerja.

Referensi kanonikal: https://flashdata.dev/id/docs/reference/realtime-and-async
Diulang: 2026-11-04 oleh FlashData

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

## Pilih sebuah mode permintaan

Google Search dan YouTube Data mendukung kedua mode tersebut. YouTube Download membutuhkan async, Batch atau Bulk; tidak mendukung realtime. Parameter sumber tetap sama ketika beralih dari real time ke async.

| Mode | Gunakan ketika | Apa yang Anda terima |
| --- | --- | --- |
| Realtime | Hasil pencarian diperlukan dalam interaksi saat ini. | Hasil tubuh dalam respon HTTP yang sama. |
| Async | Pekerjaan harus terus berlanjut setelah proses Anda terputus, atau Anda mengunduh media. | Pekerjaan ID segera; mengambil status dan hasil terpisah. |

### Meminta lifecycle

```text
Realtime POST data.flashdata.dev/v1/queries/realtime hasil
Async     POST data.flashdata.dev/v1/queries          Pekerjaan. ID
          GET  api.flashdata.dev/v2/jobs/{id}         Status ghanbe-type
          GET  api.flashdata.dev/v2/jobs/{id}/results Hasil tersembunyi
```

- [Mengirimkan banyak pertanyaan?](https://flashdata.dev/id/docs/reference/batch-and-bulk/reference.md)

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

## Kirim permintaan

Set FLASHDATA_API_KEY ke kunci yang memungkinkan google_search. Pilih realtime atau async; setiap penyerahan menjalankan satu pencarian yang dapat dihitung. Simpan skrip, penerimaan, dan hasil pada folder kerja yang sama.

Python contoh memakai Python 3.10 + dan Permintaan. Setiap skrip berjalan secara independen dan membaca berkas tersimpan dari langkah sebelumnya. The cURL kebutuhan alternatif Bash, cURL 7.76+ dan jq.

### Python sekali

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

- [API kunci dan header](https://flashdata.dev/id/docs/guides/headers-and-authentication/reference.md)
- [Google Search parameter](https://flashdata.dev/id/docs/sources/google_search/reference.md)

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

### Realtime: mendapatkan hasilnya sekarang

POST /v1/queries/realtime mengembalikan status: done dan menghasilkan array. Baca result.json; tidak ada polling yang diperlukan.

#### Python

Simpan sebagai realtime.py dan jalankan 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

##### Dapatkan hasilnya 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: simpan tanda terima pekerjaan

POST /v1/queries mengembalikan pekerjaan yang tertunda, bukan hasil pencarian. Simpan submission.json dan lanjutkan dengan status dan permintaan hasil di bawah ini.

#### Python

Simpan sebagai submit_async.py dan jalankan 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))
```

##### Ayat-ayat berikut ini adalah:

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


#### cURL / Bash

##### Kirim dan simpan pekerjaan ID · 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
```

##### Ayat-ayat berikut ini adalah:

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



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

## Periksa suatu pekerjaan async

Baca job.status menggunakan ID dalam submission.json. Untuk menunda atau memproses, tunggu penundaan Retry-After sebelum memeriksa lagi; Python dan cURL menyimpannya di status-headers.txt. Gunakan backoff jika tidak ada petunjuk yang dikembalikan. Permintaan status yang sukses tidak berarti pekerjaan telah selesai.

| job.status | Aksi berikutnya |
| --- | --- |
| pending / processing | Tunggu, kemudian periksa pekerjaan yang sama ID lagi. |
| completed | Ambil hasil yang disimpan. |
| failed | Baca job.error. Perbaiki penyebabnya sebelum mengirimkan pekerjaan baru. |

### Python

Simpan sebagai job_status.py dan jalankan 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

#### Baca status 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>

## Ambil hasil yang komplit

Jalankan ini setelah job.status selesai. Respon hasil baku adalah 302: Lokasi menunjuk ke penyimpanan yang ditandatangani URL. Kedua permintaan di bawah ini menjaga kunci API Anda pada FlashData asli dan menyimpan JSON asli ke result.json. Untuk YouTube Download, ini JSON menggambarkan media dikirim ke penyimpanan Anda; ini bukan video atau berkas audio.

### Python

Simpan sebagai job_result.py dan jalankan 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

#### Ambil yang asli JSON · 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
```


- [JSON, teks dan Markdown format](https://flashdata.dev/id/docs/guides/response-formats/reference.md#completed-results)
- [Unduh setup penyimpanan](https://flashdata.dev/id/docs/guides/youtube-download-guide/reference.md)

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

## Menangani penundaan dan kegagalan

| Situasi | Yang perlu dilakukan |
| --- | --- |
| Waktu submisi habis | Sebuah POST mungkin sudah diterima. Periksa tanda terima dan riwayat akun Anda sebelum mengajukan kembali; POST berulang dapat membuat pekerjaan yang dapat ditagih kembali. |
| 409 · result_not_ready | Tetap polling status. Jangan membuat pekerjaan lain. |
| 422 · result_not_ready | Pekerjaan gagal. Baca job.error sebelum mencoba kembali. |
| 429 | Kehormatan Retry-After atau retry_after; kurangi tingkat pengajuan ketika kapasitas tertunda penuh. |
| 410 · result_expired | Hasil tersimpan kadaluarsa 24 jam setelah selesai. Gunakan salinan disimpan Anda. |

- [Kesalahan dan kode status](https://flashdata.dev/id/docs/errors/reference.md)
- [CLI, polling dan webhook walkthrough](https://flashdata.dev/id/docs/guides/async-batch/reference.md)
