> ## Documentation Index > Fetch the complete documentation index at: https://docs.retriever.run/llms.txt > Use this file to discover all available pages before exploring further. # Lister les runs ## OpenAPI ````yaml /openapi.yaml get /v1/runs openapi: 3.1.0 info: title: Retriever Public API version: 1.0.0 description: > API publique de Retriever : lancer l'agent de prospection (runs), lire et exporter des tables, importer des données, synchroniser des listes d'exclusion, lancer des recherches structurées (Go) et appeler des services atomiques. **Authentification** : `Authorization: Bearer ret_live_…`. Créez la clé dans l'application : Paramètres → **Clés API** → **Créer une clé API**. La clé donne accès aux ressources de l'organisation de son propriétaire. **Erreurs** : toutes les erreurs HTTP ont la forme `{ "error": { "code": "…", "message": "…", "details": … } }`. Branchez votre code sur `error.code` (stable), jamais sur `message`. **Limites de débit** : les réponses authentifiées par clé portent `RateLimit-Limit`, `RateLimit-Remaining` et `RateLimit-Reset` (secondes). Une réponse `429` porte aussi `Retry-After` (secondes). Les messages d'erreur de l'API sont en anglais. contact: name: Retriever servers: - url: https://api.retriever.run description: Production - url: http://localhost:4320 description: Serveur local security: - bearerAuth: [] tags: - name: Runs description: Agent de prospection « prompt in, table out ». Asynchrone. - name: Tables description: Lecture des tables vivantes d'un workspace. - name: Workspaces description: Créer des workspaces et importer des tables. - name: Exclusions description: Listes d'entreprises et de personnes à ne jamais sourcer. - name: Go description: Recherche web autonome et extraction structurée. - name: Services description: Services atomiques (recherche, scraping, email…). - name: Credits description: Solde de crédits. paths: /v1/runs: get: tags: - Runs summary: Lister les runs operationId: listRuns parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - name: workspace_id in: query schema: type: string description: Filtre par workspace. - name: conversation_id in: query schema: type: string description: Filtre par conversation. responses: '200': description: Page de runs, du plus récent au plus ancien. content: application/json: schema: type: object required: - items - next_offset properties: items: type: array items: $ref: '#/components/schemas/Run' next_offset: type: - integer - 'null' description: '`null` à la fin.' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: Limit: name: limit in: query schema: type: integer minimum: 1 maximum: 1000 default: 100 Offset: name: offset in: query schema: type: integer minimum: 0 default: 0 schemas: Run: type: object properties: id: type: string workspace_id: type: string conversation_id: type: string status: type: string enum: - queued - running - recovering - completed - failed - cancelled message: type: - string - 'null' description: Texte final de l'agent. artifacts: type: array description: Tables créées ou modifiées par le run (état vivant). items: type: object properties: type: const: table id: type: string name: type: string effect: type: string enum: - created - updated links: type: object properties: self: type: string rows: type: string last_heartbeat_at: type: - string - 'null' format: date-time progress: type: object properties: phase: type: - string - 'null' updated_at: type: string output: type: - object - 'null' properties: type: type: string enum: - json - tables links: type: object properties: self: type: string error: type: - object - 'null' properties: code: type: string message: type: string created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: - string - 'null' format: date-time completed_at: type: - string - 'null' format: date-time cancellation_requested: type: boolean links: type: object properties: self: type: string app: type: string description: >- Ouvre la conversation du run, et ses tables, dans l'app Retriever (session requise). example: id: run_001 workspace_id: ws_001 conversation_id: conv_001 status: completed message: J'ai créé la table Fintechs FR avec 30 entreprises. artifacts: - type: table id: tbl_001 name: Fintechs FR effect: created links: self: /v1/tables/tbl_001 rows: /v1/tables/tbl_001/rows output: null error: null cancellation_requested: false links: self: /v1/runs/run_001 app: >- https://app.retriever.so/app/workspaces/ws_001/conversations/conv_001 Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Code stable, à utiliser dans votre code. message: type: string description: Explication lisible. Peut changer. details: description: Détails optionnels (ex. liste des champs invalides). responses: BadRequest: description: >- `invalid_request` : JSON illisible, champ ou paramètre de requête inconnu, type incorrect, `limit` hors bornes, `Idempotency-Key` vide, contrat `output` invalide. `message` nomme chaque champ en faute, `details` les liste sous forme `{ path, message }`. Sur `POST /v1/runs`, `workspace_mismatch` : la conversation n'appartient pas au workspace fourni. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: 'prompt: prompt must not be blank' details: - path: prompt message: prompt must not be blank Unauthorized: description: >- `not_authenticated` : header absent, mal formé (attendu `Bearer `), clé révoquée ou inconnue. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_authenticated message: A valid API key is required. TooManyRequests: description: '`rate_limited` : attendez `Retry-After` secondes puis réessayez.' headers: Retry-After: schema: type: integer RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Rate limit exceeded. Retry later. headers: RateLimit-Limit: schema: type: integer description: Budget de la fenêtre. RateLimit-Remaining: schema: type: integer description: Requêtes restantes. RateLimit-Reset: schema: type: integer description: Secondes avant la remise à zéro. securitySchemes: bearerAuth: type: http scheme: bearer description: Clé API `ret_live_…` créée dans Settings → API keys. ````