> ## 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. # Get apicompanies > Search for business leads matching the given filters and return a preview. **Prerequisites:** Authenticated with a valid JWT. The response includes `totalCount` which tells you how many credits an export will cost. Use this endpoint to refine filters before calling `/api/download-csv/`. ## OpenAPI ````yaml /api-reference/openapi.json get /api/companies/ 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/companies/: get: tags: - Search description: >- Search for business leads matching the given filters and return a preview. **Prerequisites:** Authenticated with a valid JWT. The response includes `totalCount` which tells you how many credits an export will cost. Use this endpoint to refine filters before calling `/api/download-csv/`. operationId: companies_retrieve parameters: - in: query name: category schema: type: integer description: Filter by category ID (from GET /api/categories/). - in: query name: countries schema: type: array items: type: string description: >- Filter by country alpha-2 codes (e.g. 'FR', 'AU'). Repeat for multiple. - in: query name: include_closed_businesses schema: type: boolean enum: - false - true description: >- Set to 'true' to include permanently closed businesses in the preview count. Defaults to 'false'. - in: query name: level2_locations schema: type: array items: type: string description: Filter by level-2 location codes (states/departments). responses: '200': content: application/json: schema: $ref: '#/components/schemas/CompaniesFilterResponse' description: '' security: - ApiKeyAuth: [] x-codeSamples: - lang: cURL source: |- curl -X GET 'https://www.spherescout.io/api/companies/' \ -H 'Authorization: Token YOUR_API_KEY' \ -H 'User-Agent: SphereScout/1.0' - lang: Python source: |- import requests response = requests.get( "https://www.spherescout.io/api/companies/", headers={ "Authorization": "Token YOUR_API_KEY", "User-Agent": "SphereScout/1.0", }, ) print(response.json()) - lang: JavaScript source: >- const response = await fetch("https://www.spherescout.io/api/companies/", { headers: { "Authorization": "Token YOUR_API_KEY", "User-Agent": "SphereScout/1.0", }, }); const data = await response.json(); components: schemas: CompaniesFilterResponse: type: object properties: preview: type: array items: $ref: '#/components/schemas/CompanyPreview' description: >- Paginated list of matching companies (preview only, no full contact data). totalCount: type: integer description: >- Total number of leads matching the filters. Use this to estimate credit cost before exporting. cities: type: array items: type: string description: Distinct cities in the result set. zipCodes: type: array items: type: string description: Distinct zip/postal codes in the result set. categories: type: array items: type: array items: {} description: Categories represented in the result set. required: - preview - totalCount CompanyPreview: type: object properties: id: type: integer description: Unique company identifier. name: type: string description: Business name. email: type: array items: type: string description: List of email addresses. phone: type: string description: Primary phone number. city: type: string description: City where the business is located. country: type: string description: Country name. level2_location: type: string description: State, region, or department name. required: - city - country - email - id - level2_location - name - phone securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'API key. Format: Token ' ````