Cloud Storage · Documentation Crawlbase

Endpoint

GEThttps://api.crawlbase.com/storage

# Two operations: store (write) and retrieve (read).
# Storage is implicit — set store=true on a Crawling API call to write.
# Use this endpoint to read.

Stockage des pages

Vous n'appelez pas cet endpoint pour stocker. Ajoutez plutôt store=true à n'importe quel appel à la Crawling API. La page est stockée automatiquement et vous recevez un rid dans la réponse.

curl 'https://api.crawlbase.com/?token=YOUR_TOKEN' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'store=true' -G

# Response includes rid: a1B2c3D4e5F6

Récupération des pages

Par RID

curl 'https://api.crawlbase.com/storage?token=YOUR_TOKEN&rid=a1B2c3D4e5F6'
from crawlbase import StorageAPI

api = StorageAPI({'token': 'YOUR_TOKEN'})
res = api.get(rid='a1B2c3D4e5F6')
print(res['body'])
const { StorageAPI } = require('crawlbase');
const api = new StorageAPI({ token: 'YOUR_TOKEN' });

const res = await api.get({ rid: 'a1B2c3D4e5F6' });
console.log(res.body);

Par URL

Récupérez une page stockée à partir de son URL d'origine. Renvoie la version stockée la plus récente.

curl 'https://api.crawlbase.com/storage?token=YOUR_TOKEN&url=https%3A%2F%2Fexample.com'

Paramètres

token

stringrequis

Votre token Crawlbase.

rid

stringl'un de

Identifiant de requête renvoyé lors du stockage de la page.

url

stringl'un de

URL d'origine. Renvoie la version stockée la plus récente. À encoder en URL.

format

html | jsonhtml

Enveloppe de la réponse. json encapsule le body et les métadonnées.

Récupération en masse

Récupérez jusqu'à 100 pages stockées en un seul aller-retour par RID. Envoyez en POST un body JSON contenant la liste et (en option) demandez au serveur de supprimer chaque entrée au fur et à mesure de son renvoi — pratique pour les pipelines de type « vidage de file » qui n'ont pas besoin de garder le stockage actif.

POSThttps://api.crawlbase.com/storage/bulk

curl -X POST 'https://api.crawlbase.com/storage/bulk?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "rids": ["RID1","RID2","RID3"], "auto_delete": true }'

rids

string[]requis

Tableau de RIDs à récupérer. Maximum 100 par requête — tout ce qui dépasse 100 est ignoré silencieusement.

auto_delete

booleanfalse

Lorsque true, chaque entrée renvoyée avec succès est supprimée du stockage dans le même appel. Utilisez cette option lorsque vous videz une file de résultats à usage unique que vous n'avez pas besoin de conserver.

La réponse est un tableau JSON, avec un objet par RID renvoyé. Le champ body est encodé en base64 et compressé en gzip — décodez le base64 puis décompressez le gzip pour obtenir la page d'origine.

[
  {
    "stored_at": "2021-03-01T14:22:58+02:00",
    "original_status": 200,
    "pc_status": 200,
    "rid": "RID1",
    "url": "https://example.com/a",
    "body": "H4sIAAAA…"  // base64(gzip(html))
  },
  {
    "stored_at": "2021-03-01T14:30:51+02:00",
    "original_status": 200,
    "pc_status": 200,
    "rid": "RID2",
    "url": "https://example.com/b",
    "body": "H4sIAAAA…"
  }
]

Suppression en masse

Supprimez une liste de RIDs en un seul appel. Renvoie un statut par RID afin que vous puissiez repérer ceux qui avaient déjà disparu ou qui ont échoué.

POSThttps://api.crawlbase.com/storage/bulk_delete

curl -X POST 'https://api.crawlbase.com/storage/bulk_delete?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "rids": ["RID1","RID2","RID3"] }'

La réponse est un tableau JSON, avec une entrée par RID soumis. status: true signifie que l'entrée a été supprimée ; status: false avec result: "Not Found" signifie que le RID n'existait pas (déjà nettoyé, expiré ou jamais écrit).

[
  { "rid": "RID1", "result": "Deleted",   "status": true  },
  { "rid": "RID2", "result": "Not Found", "status": false },
  { "rid": "RID3", "result": "Failed",    "status": false }
]

La suppression est irréversible

Vérifiez deux fois la liste de RIDs avant l'envoi. Il n'y a ni suppression douce ni annulation — si vous avez besoin d'un workflow réversible, récupérez d'abord avec auto_delete=false et n'appelez /bulk_delete qu'une fois le body persisté localement.

Supprimer une seule page

Retirez une entrée du stockage par RID. Utilisez DELETE /storage avec le RID dans la query string.

DELETEhttps://api.crawlbase.com/storage

curl -X DELETE 'https://api.crawlbase.com/storage?token=YOUR_TOKEN&rid=RID'

Trois formes de réponse :

Résultat	Body
Trouvée et supprimée	`{"success": "The Storage item has been deleted successfully"}`
Trouvée mais suppression échouée	`{"error": "The Storage item could not be deleted"}`
Absente du stockage	`{"error": "Not Found"}`

Lister les RIDs

Parcourez les RIDs de votre zone de stockage — l'appel d'inventaire. Pour les jeux de données plus volumineux qu'une seule réponse, utilisez la pagination par scroll (scroll=true initialise une session de scroll et renvoie un scroll_id à rejouer sur les appels suivants).

GEThttps://api.crawlbase.com/storage/rids

# First page
curl 'https://api.crawlbase.com/storage/rids?token=YOUR_TOKEN&limit=100&scroll=true'

# Next page — replay the scroll_id from the previous response
curl 'https://api.crawlbase.com/storage/rids?token=YOUR_TOKEN&scroll_id=dXVlcnlUaGVuRmV0Y2g7…'

limit

integeroptionnel

Nombre maximum de RIDs à renvoyer par appel. Le plafond est de 10000. Pas de valeur par défaut — définissez-la explicitement.

scroll

booleanfalse

Lorsque true , la réponse inclut un scroll_id que vous pouvez rejouer pour récupérer la page suivante. Sans cela, vous n'obtenez que la première page.

scroll_id

stringoptionnel

Token issu d'une réponse précédente. Rejouez-le pour faire avancer le scroll. Ne passez pas scroll=true sur les appels suivants — uniquement sur le premier appel.

scroll_order

asc | descdesc

Trie les RIDs par horodatage stocké. Par défaut, du plus récent au plus ancien.

{
  "rids": ["RID1", "RID2", "RID3", "..."],
  "scroll_id": "dXVlcnlUaGVuRmV0Y2g7NTs1NDpDV…"
}

Les sessions de scroll expirent

Un scroll_id est valable environ 15 secondes d'inactivité. Si vous voyez "Scroll session has expired or is invalid" , recommencez avec une nouvelle requête scroll=true — le curseur a disparu.

Nombre total

Un seul entier : le nombre de pages actuellement présentes dans votre zone de stockage.

GEThttps://api.crawlbase.com/storage/total_count

curl 'https://api.crawlbase.com/storage/total_count?token=YOUR_TOKEN'

# Response
# { "totalCount": 5491078 }

Rétention et tarification

Les pages stockées sont conservées 14 jours par défaut . Extensible sur les plans entreprise.
Chaque appel store=true compte comme une seule requête — sans frais supplémentaires.
La récupération (ce point de terminaison) est gratuite . Lisez autant de fois que nécessaire.
Si une page est re-crawlée avec store=true , la nouvelle version remplace l'ancienne.

Quand le stockage brille

Pistes d'audit (« que disait la page lorsque nous l'avons crawlée ? »), pipelines de retraitement (re-parser le HTML stocké lorsque la logique de votre scraper s'améliore) et diffusion de résultats mis en cache aux lecteurs sans re-crawler.