Quickstart

À la fin, vous aurez lancé l’agent Retriever par API et lu une vraie liste d’entreprises. Prérequis

Un compte Retriever avec quelques crédits.
curl et jq (brew install jq, apt install jq). Ou Node 18+, ou Python 3.9+ : voir les scripts complets.

Créer une clé API (1 min)

Ouvrez l’application Retriever.
Allez dans Paramètres → Clés API.
Cliquez sur Créer une clé API, puis confirmez avec Créer la clé.
Copiez la clé ret_live_…. Elle n’est affichée qu’une fois.

export RETRIEVER_API_URL="https://api.retriever.run"
export RETRIEVER_API_KEY="ret_live_..."

Vérifier la clé (15 s)

/credits n’a pas de préfixe /v1.

curl -s "$RETRIEVER_API_URL/credits" -H "Authorization: Bearer $RETRIEVER_API_KEY"

Résultat attendu :

{ "remainingCredits": 842.5 }

Vous recevez	Cause	Correction
`not_authenticated`	Clé absente, mal copiée ou révoquée.	Relancez `export RETRIEVER_API_KEY=…` sans espace ni guillemet en trop.
`Could not resolve host`	Mauvaise base URL.	Vérifiez `RETRIEVER_API_URL`.
`remainingCredits` à `0`	Pas de crédits.	Rechargez avant l’étape suivante.

Lancer un run (15 s)

Une petite demande, pour un résultat rapide :

RUN_ID=$(curl -s -X POST "$RETRIEVER_API_URL/v1/runs" \
  -H "Authorization: Bearer $RETRIEVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Trouve 5 startups SaaS B2B basées à Lyon, avec leur site web.",
    "output": { "type": "tables", "tables": [{ "key": "startups" }] }
  }' | tee /dev/stderr | jq -r .id)
echo "RUN_ID=$RUN_ID"

Réponse 202 Accepted (extrait) :

{
  "id": "run_8f2c1a",
  "workspace_id": "ws_41b0",
  "conversation_id": "conv_77e2",
  "status": "queued",
  "links": { "self": "/v1/runs/run_8f2c1a" }
}

output demande à l’agent de publier sa table sous la clé startups. Vous saurez exactement quoi lire à la dernière étape.
Retriever a créé un workspace et une conversation. Vous les verrez aussi dans l’application.
Si RUN_ID vaut null, lisez l’erreur affichée au-dessus.

Attendre la fin (1 à 3 min)

for i in $(seq 1 40); do
  RUN=$(curl -s "$RETRIEVER_API_URL/v1/runs/$RUN_ID" -H "Authorization: Bearer $RETRIEVER_API_KEY")
  STATUS=$(echo "$RUN" | jq -r '.status // "error"')
  echo "$(date +%T) status=$STATUS phase=$(echo "$RUN" | jq -r '.progress.phase // "-"')"
  case "$STATUS" in
    queued|running|recovering) sleep 15 ;;
    *) break ;;
  esac
done
echo "$RUN" | jq '{status, message, error}'

La boucle s’arrête sur un statut terminal, sur une erreur HTTP, ou après 10 minutes.

{
  "status": "completed",
  "message": "J'ai trouvé 5 startups SaaS B2B lyonnaises et publié la table.",
  "error": null
}

Résultat	Que faire
`status=failed`	Lisez `error.message`. Vérifiez vos crédits.
`status=error`	Réponse HTTP en erreur : `echo "$RUN"` affiche `error.code`.
Toujours `running` après 10 min	Relancez la boucle : le run continue côté serveur.

Lire le résultat (15 s)

curl -s "$RETRIEVER_API_URL/v1/runs/$RUN_ID/output/tables/startups/rows?limit=10" \
  -H "Authorization: Bearer $RETRIEVER_API_KEY" | jq '.items[].values'

{ "company_name": "Exemple SaaS", "website": "https://exemple.io" }
{ "company_name": "Autre Startup", "website": "https://autre.fr" }

Les noms de colonnes dépendent de l’agent. Pour les imposer, ajoutez un row_schema : voir Obtenir une table au format garanti.

Vous avez fait votre premier appel API authentifié et obtenu une liste de prospects.

Même parcours en Node.js ou Python

const API = process.env.RETRIEVER_API_URL;
const headers = {
  Authorization: `Bearer ${process.env.RETRIEVER_API_KEY}`,
  "Content-Type": "application/json",
};

async function call(path, init = {}) {
  const res = await fetch(`${API}${path}`, { ...init, headers });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
  return body;
}

const created = await call("/v1/runs", {
  method: "POST",
  body: JSON.stringify({
    prompt: "Trouve 5 startups SaaS B2B basées à Lyon, avec leur site web.",
    output: { type: "tables", tables: [{ key: "startups" }] },
  }),
});
console.log("run", created.id);

let run = created;
for (let i = 0; ["queued", "running", "recovering"].includes(run.status); i++) {
  if (i >= 40) throw new Error("Toujours en cours après 10 min. Le run continue côté serveur.");
  await new Promise((r) => setTimeout(r, 15_000));
  run = await call(`/v1/runs/${created.id}`);
  console.log("status", run.status, run.progress?.phase ?? "");
}
if (run.status !== "completed") throw new Error(run.error?.message ?? run.status);

const page = await call(`/v1/runs/${run.id}/output/tables/startups/rows?limit=10`);
console.table(page.items.map((row) => row.values));

import os, time, requests

API = os.environ["RETRIEVER_API_URL"]
HEADERS = {"Authorization": f"Bearer {os.environ['RETRIEVER_API_KEY']}"}

def call(method, path, **kw):
    res = requests.request(method, f"{API}{path}", headers=HEADERS, timeout=30, **kw)
    body = res.json()
    if not res.ok:
        err = body["error"]
        raise RuntimeError(f"{res.status_code} {err['code']}: {err['message']}")
    return body

run = call("POST", "/v1/runs", json={
    "prompt": "Trouve 5 startups SaaS B2B basées à Lyon, avec leur site web.",
    "output": {"type": "tables", "tables": [{"key": "startups"}]},
})
print("run", run["id"])

for i in range(41):
    if run["status"] not in ("queued", "running", "recovering"):
        break
    if i == 40:
        raise RuntimeError("Toujours en cours après 10 min. Le run continue côté serveur.")
    time.sleep(15)
    run = call("GET", f"/v1/runs/{run['id']}")
    print("status", run["status"], (run.get("progress") or {}).get("phase"))

if run["status"] != "completed":
    raise RuntimeError((run.get("error") or {}).get("message", run["status"]))

page = call("GET", f"/v1/runs/{run['id']}/output/tables/startups/rows", params={"limit": 10})
for row in page["items"]:
    print(row["values"])

Lancez node quickstart.mjs (Node 18+) ou python quickstart.py (pip install requests).

Et ensuite

Imposer les colonnes du résultat : Obtenir une table au format garanti.
Enrichir votre propre liste : Enrichir une liste de votre CRM.
Comprendre les runs, sorties et artefacts : Runs.

Démarrer

Concepts

Recettes

Même parcours en Node.js ou Python

Et ensuite

​Même parcours en Node.js ou Python

​Et ensuite

Même parcours en Node.js ou Python

Et ensuite