> ## 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 apiusersearch history > List all past lead searches for the authenticated user. Each entry includes the search ID, credits consumed, processing status, and the filters that were used. Use `id` with the download-status and download-completed-csv endpoints. ## OpenAPI ````yaml /api-reference/openapi.json get /api/user/search-history/ 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/user/search-history/: get: tags: - History description: >- List all past lead searches for the authenticated user. Each entry includes the search ID, credits consumed, processing status, and the filters that were used. Use `id` with the download-status and download-completed-csv endpoints. operationId: user_search_history_list responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/SearchHistoryItem' description: '' security: - ApiKeyAuth: [] x-codeSamples: - lang: cURL source: |- curl -X GET 'https://www.spherescout.io/api/user/search-history/' \ -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/user/search-history/", 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/user/search-history/", { headers: { "Authorization": "Token YOUR_API_KEY", "User-Agent": "SphereScout/1.0", }, }); const data = await response.json(); components: schemas: SearchHistoryItem: type: object properties: id: type: integer description: Search ID. Use this to check download status. display_name: type: string nullable: true credits: type: integer description: Number of leads (= credits consumed). lead_count: type: integer description: Number of leads in the exported file. created_at: type: string format: date-time description: When the search was initiated (ISO 8601). status: type: string description: 'Processing status: PENDING, PROCESSING, COMPLETED, or FAILED.' link_expires_at: type: string format: date-time nullable: true description: >- When the download link expires (ISO 8601). Null if not yet available. metadata: type: object additionalProperties: {} description: Search filters used (countries, categories, locations). export_kind: type: string description: 'Export type: full or delta.' baseline_search_id: type: integer nullable: true is_limited_by_credits: type: boolean freshness: type: object additionalProperties: {} nullable: true description: Last checked fresh data report for this search. freshness_checked_at: type: string format: date-time nullable: true freshness_check_available: type: boolean freshness_next_check_at: type: string format: date-time nullable: true fresh_export_in_progress: type: boolean required: - baseline_search_id - created_at - credits - display_name - export_kind - fresh_export_in_progress - freshness - freshness_check_available - freshness_checked_at - freshness_next_check_at - id - is_limited_by_credits - lead_count - link_expires_at - metadata - status securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'API key. Format: Token ' ````