Requêtes et pagination

GET d’une liste ou POST d’une requête#

GET /{resource} et POST /{resource}/query utilisent le même chemin de lecture. GET encode les filtres dans le paramètre singulier filter ; POST utilise un tableau filters dans son corps JSON. POST /query fonctionne avec une clé en lecture seule. Un paramètre inconnu ou répété renvoie 400 invalid_request.

Utiliser des filtres certifiés#

Chaque filtre contient field, op et, si nécessaire, value. Les champs, opérateurs et valeurs sont vérifiés selon les capacités de l’espace. Un champ natif utilise sa clé ; un champ personnalisé utilise le filter_key décrit ; un champ lié utilise rel:<foreign-key-column>.<column>.

curl --fail-with-body --request POST "$SQUARIO_API_BASE/companies/query" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": [{ "field": "name", "op": "iLike", "value": "Northfold" }],
    "join": "and",
    "page_size": 25,
    "fields": ["name"]
  }'

curl --fail-with-body --get "$SQUARIO_API_BASE/companies" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --data-urlencode 'filter=[{"field":"name","op":"iLike","value":"Northfold"}]' \
  --data-urlencode 'fields=name' \
  --data-urlencode 'page_size=25'

Lire les métadonnées de pagination#

Une liste renvoie data et meta. Le mode page inclut page, page_size, total et has_more. Lorsque total_is_capped vaut true, total est une borne inférieure. Les pages adressent une fenêtre de décalage jusqu’à 10 000 ; au-delà, la requête renvoie 400 avec details.max_page. Pour les exports et synchronisations profondes, utilisez des curseurs.

{
  "data": [{ "id": "c91b7028-f985-4bc1-9f75-c76533c3133a", "name": "Northfold" }],
  "meta": { "page": 1, "page_size": 25, "total": 1, "has_more": false }
}

Parcourir avec un curseur opaque#

Envoyez cursor=start, puis renvoyez meta.next_cursor sans le modifier jusqu’à ce qu’il soit null. N’ajoutez pas page. Conservez les mêmes filtres, tri et paramètres pendant le parcours. Un curseur indique une position, pas un instantané d’un espace de travail qui évolue.

• Les réponses par curseur contiennent page_size, next_cursor, cursor_supported, total et has_more.
• Le tri par pertinence textuelle ne permet pas de parcours ; cursor_supported vaut false sur la première page. Utilisez le mode page pour cette requête.
• Un curseur positionné incompatible avec la requête renvoie 400. Recommencez après une modification du tri ou des filtres.
• Traitez les curseurs comme opaques. Ne les décodez pas, ne les modifiez pas et ne les fabriquez pas.

const base = process.env.SQUARIO_API_BASE?.replace(/\/$/, "");
const key = process.env.SQUARIO_API_KEY;
if (!base || !key) throw new Error("Set SQUARIO_API_BASE and SQUARIO_API_KEY");

let cursor = "start";
while (cursor !== null) {
  const url = new URL(`${base}/companies`);
  url.searchParams.set("cursor", cursor);
  url.searchParams.set("page_size", "100");
  url.searchParams.set("fields", "name");

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${key}` },
    signal: AbortSignal.timeout(30_000),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(`${body.error.code} (${body.error.request_id})`);
  if (!body.meta.cursor_supported) throw new Error("Use page mode for this sort");

  for (const record of body.data) console.log(record.id, record.name);
  cursor = body.meta.next_cursor;
}