> ## Documentation Index > Fetch the complete documentation index at: https://docs.spherescout.io/llms.txt > Use this file to discover all available pages before exploring further. # Post apidownload csv > Initiate an asynchronous lead export. **Prerequisites:** Authenticated. Sufficient credits (1 per lead). Credits are deducted immediately. The response contains a `search_id` — use it to poll `/api/download-status/{search_id}/` until the file is ready. ## OpenAPI ````yaml /api-reference/openapi.json post /api/download-csv/ openapi: 3.0.3 info: title: SphereScout API version: 1.0.0 description: > # SphereScout API SphereScout provides B2B lead data — business contacts with emails, phone numbers, and location metadata — across multiple countries. ## Authentication All endpoints (except `/api/auth/` and `/api/plans`) require a **JWT Bearer token**. 1. **Register** — `POST /api/auth/sign-up/` 2. **Login** — `POST /api/auth/login/` → returns `access` and `refresh` tokens 3. **Attach header** — `Authorization: Bearer ` 4. **Refresh** — `POST /api/token/refresh/` with `{ "refresh": "" }` Access tokens expire after 60 minutes. Refresh tokens are long-lived. ## Credits Every account has a credit balance. Exporting leads costs **1 credit per lead**. Check your balance via `GET /api/user/profile/`. Credits reset each billing cycle for subscribed users. ## Async Download Workflow Exporting leads is asynchronous: 1. **Search** — `GET /api/companies/` to preview results and get `totalCount` 2. **Export** — `POST /api/download-csv/` to start generation (credits deducted immediately) 3. **Poll** — `GET /api/download-status/{search_id}/` until `status = COMPLETED` 4. **Download** — `GET /api/download-completed-csv/{search_id}/` to get a signed URL ## API Keys (recommended for integrations) Generate a persistent API key from your dashboard under **API Keys**. Attach it to every request: ``` Authorization: Token ``` Keys can be given an expiry date and revoked at any time. JWT Bearer tokens (`Authorization: Bearer `) continue to work for browser sessions and Swagger UI testing. ## Rate Limiting API requests are rate-limited. If you receive a `429` response, back off and retry. ## Versioning This is **v1** of the API. Breaking changes will be communicated in advance. servers: - url: https://www.spherescout.io security: [] tags: - name: Authentication description: Register, login, refresh tokens, and reset passwords. - name: Search description: Search and preview business leads by country, category, and location. - name: Download description: 'Export leads to CSV/Excel. Async workflow: initiate → poll → download.' - name: History description: View past searches and their download status. - name: Credits & Profile description: Check credit balance, subscription plan, and user profile. - name: Geography description: Countries, states/regions, counties, and cities for search filters. - name: API Keys description: Create, list, and revoke persistent API keys for integrations. paths: /api/download-csv/: post: tags: - Download description: >- Initiate an asynchronous lead export. **Prerequisites:** Authenticated. Sufficient credits (1 per lead). Credits are deducted immediately. The response contains a `search_id` — use it to poll `/api/download-status/{search_id}/` until the file is ready. operationId: download_csv_create parameters: - in: query name: category schema: type: integer description: Category ID to filter. - in: query name: countries schema: type: array items: type: string description: Country alpha-2 codes to export. - in: query name: export_format schema: type: string enum: - csv - excel - xlsx description: 'Output format: ''excel'' (default), ''csv'', or ''xlsx''.' - in: query name: include_additional_fields schema: type: boolean enum: - false - true description: >- Set to 'true' to append coordinates, rating, review count, claimed status, opening hours, and business status to the export. Defaults to 'false'. - in: query name: include_closed_businesses schema: type: boolean enum: - false - true description: >- Set to 'true' to include permanently closed businesses in the search and export. Defaults to 'false'. responses: '200': content: application/json: schema: $ref: '#/components/schemas/DownloadCsvResponse' description: '' '403': content: application/json: schema: $ref: '#/components/schemas/InsufficientCreditsResponse' description: '' security: - ApiKeyAuth: [] x-codeSamples: - lang: cURL source: |- curl -X POST 'https://www.spherescout.io/api/download-csv/' \ -H 'Authorization: Token YOUR_API_KEY' \ -H 'User-Agent: SphereScout/1.0' \ -H 'Content-Type: application/json' \ -d '{}' - lang: Python source: |- import requests response = requests.post( "https://www.spherescout.io/api/download-csv/", headers={ "Authorization": "Token YOUR_API_KEY", "User-Agent": "SphereScout/1.0", }, json={}, ) print(response.json()) - lang: JavaScript source: >- const response = await fetch("https://www.spherescout.io/api/download-csv/", { method: "POST", headers: { "Authorization": "Token YOUR_API_KEY", "User-Agent": "SphereScout/1.0", "Content-Type": "application/json", }, body: JSON.stringify({}), }); const data = await response.json(); components: schemas: DownloadCsvResponse: type: object properties: status: type: string description: '''processing'' on success, ''error'' on failure.' validation_code: type: string description: >- Machine-readable status code: 'processing_started', 'no_leads_found', 'insufficient_credits'. search_id: type: integer description: ID to poll download status. Only present when status='processing'. lead_count: type: integer description: >- Number of leads being exported (= credits deducted). Present on success and no_leads_found. required: - status - validation_code InsufficientCreditsResponse: type: object properties: status: type: string description: Always 'error'. validation_code: type: string description: Always 'insufficient_credits'. required_credits: type: integer description: Number of credits needed for this export. available_credits: type: integer description: Credits currently available on the account. required: - available_credits - required_credits - status - validation_code securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'API key. Format: Token ' ````