### Install keyscore-py using pip

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Installs the keyscore-py Python client library. This is the first step to using the library for API interactions.

```bash
pip install keyscore-py
```

--------------------------------

### Get keyscore-py Available Data Sources

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Fetches a list of available data sources from the keysco.re API, including their names, descriptions, and allowed data types.

```python
sources = client.sources()
for source in sources:
    print(f"{source.name}: {source.description}")
    print(f"Types: {source.allowedTypes}")
```

--------------------------------

### Get machine information by UUID using keyscore-py

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Retrieves information about a machine identified by its UUID, including its computer name, operating system, and current user.

```python
machine = client.machine_info("550e8400-e29b-41d4-a716-446655440000")
if machine:
    print(f"Computer: {machine.computerName}")
    print(f"OS: {machine.operationSystem}")
    print(f"User: {machine.userName}")
```

--------------------------------

### Complete Threat Investigation Workflow with keyscore-py

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

This Python script demonstrates a comprehensive threat investigation process using the keyscore-py library. It connects to the keysco.re API, checks its health, searches for a given email address, extracts associated IP addresses and file hashes from the search results, performs lookups for these indicators, and prints a summary report. It requires the 'keyscore' library to be installed and an API key for authentication.

```python
from keyscore import Client, SearchRequest, IPLookupRequest, HashLookupRequest
import json

def investigate_threat(email_address: str, api_key: str):
    """Complete threat investigation workflow"""
    client = Client(base_url="https://api.keysco.re", api_key=api_key)

    # Step 1: Check API health
    try:
        health = client.health()
        if health.status != "ok":
            print("API not healthy, aborting")
            return
    except Exception as e:
        print(f"Cannot connect to API: {e}")
        return

    # Step 2: Get available sources
    sources_resp = client.sources()
    print(f"Searching across {len(sources_resp.sources)} sources\n")

    # Step 3: Search for the email
    print(f"=== Investigating: {email_address} ===\n")

    search_req = SearchRequest(
        terms=[email_address],
        types=["email"],
        source="all",
        pagesize=50
    )

    search_results = client.search(search_req)
    print(f"Found {search_results.size} results (took {search_results.took}ms)")

    # Collect IPs and hashes from results
    ip_addresses = set()
    hashes = set()

    if search_results.results:
        for source, records in search_results.results.items():
            print(f"\nSource: {source} ({len(records)} records)")
            for record in records[:3]:
                print(f"  {record.get('value')} [{record.get('date')}]")

                # Extract IPs from metadata
                if 'ip' in record.get('metadata', {}):
                    ip_addresses.add(record['metadata']['ip'])

                # Extract hashes from metadata
                if 'hash' in record.get('metadata', {}):
                    hashes.add(record['metadata']['hash'])

    # Step 4: Lookup discovered IP addresses
    if ip_addresses:
        print(f"\n=== IP Address Analysis ({len(ip_addresses)} unique) ===")
        ip_req = IPLookupRequest(terms=list(ip_addresses))
        ip_results = client.ip_lookup(ip_req)

        for ip, info in ip_results.results.items():
            print(f"\n{ip}:")
            print(f"  Location: {info.city}, {info.country}")
            print(f"  ISP: {info.isp}")
            print(f"  Organization: {info.org}")

    # Step 5: Lookup discovered hashes
    if hashes:
        print(f"\n=== Hash Analysis ({len(hashes)} unique) ===")
        hash_req = HashLookupRequest(terms=list(hashes))
        hash_results = client.hash_lookup(hash_req)

        for hash_val, record in hash_results.results.items():
            print(f"\n{record.hash[:16]}...:")
            print(f"  Type: {record.type}")
            print(f"  Plaintext: {record.plaintext}")
            print(f"  Source: {record.source}")

    # Step 6: Generate summary report
    print("\n=== Investigation Summary ===")
    print(f"Target: {email_address}")
    print(f"Total Records: {search_results.size}")
    print(f"IP Addresses: {len(ip_addresses)}")
    print(f"Hashes Found: {len(hashes)}")
    print(f"Query Time: {search_results.took}ms")

# Run investigation
if __name__ == "__main__":
    investigate_threat("target@example.com", "your-api-key-here")

```

--------------------------------

### Detailed Count by Source API

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Get a breakdown of result counts per data source.

```APIDOC
## Detailed Count by Source API

### Description
Get a breakdown of result counts per data source.

### Method
POST

### Endpoint
`/count/detailed`

### Parameters
#### Request Body
- **terms** (array of strings) - Required - The search terms to count.
- **types** (array of strings) - Required - The data types to search within.
- **source** (string) - Optional - The data source(s) to query. Defaults to all sources if not specified.
- **wildcard** (boolean) - Optional - Whether to enable wildcard matching for terms.
- **dateFrom** (string) - Optional - The start date for the search range (YYYY-MM-DD).
- **dateTo** (string) - Optional - The end date for the search range (YYYY-MM-DD).
- **operator** (string) - Optional - The logical operator to combine terms ('AND' or 'OR'). Defaults to 'OR'.
- **regex** (boolean) - Optional - Whether to interpret terms as regular expressions.

### Request Example
```python
from keyscore import Client, CountRequest

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    count_req = CountRequest(
        terms=["admin@example.com"],
        types=["email"],
        regex=False
    )
    detailed_count = client.count_detailed(count_req)
    print(f"Total: {detailed_count.total_count} (took {detailed_count.took}ms)")
    for source_name, count in detailed_count.counts.items():
        print(f"  {source_name}: {count} results")
except APIError as e:
    print(f"Detailed count failed: {e}")
```

### Response
#### Success Response (200)
- **total_count** (integer) - The total number of results across all sources.
- **took** (integer) - The time taken in milliseconds to fulfill the request.
- **counts** (object) - A dictionary where keys are source names and values are the counts of results from that source.

#### Response Example
```json
{
  "total_count": 523,
  "took": 145,
  "counts": {
    "breach_db_2023": 312,
    "leak_collection_v2": 189,
    "combo_lists": 22
  }
}
```
```

--------------------------------

### Count Search Results

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Gets the total count of results for a given query, optionally filtered by specific sources.

```APIDOC
## GET /count

### Description
Gets the total count of results for a given query.

### Method
GET

### Endpoint
/count

### Parameters

#### Query Parameters
- **query** (string) - Required - The search query.
- **sources** (array of strings) - Optional - A list of source names to filter the count by.

### Request Example
```python
# Count across all sources
total = client.count("example@domain.com")

# Count from specific sources
total = client.count("example@domain.com", sources=["source1", "source2"])
```

### Response
#### Success Response (200)
- **count** (integer) - The total number of results found for the query.

#### Response Example
```json
{
  "count": 150
}
```
```

--------------------------------

### Get detailed count breakdown by source in keyscore-py

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Retrieves a detailed breakdown of result counts for a query, separated by each data source.

```python
counts = client.count_detailed("example@domain.com")
for count in counts:
    print(f"{count.source}: {count.count} results")
```

--------------------------------

### Count Results API

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Get the total count of results matching search criteria across sources.

```APIDOC
## Count Results API

### Description
Get the total count of results matching search criteria across sources.

### Method
POST

### Endpoint
`/count`

### Parameters
#### Request Body
- **terms** (array of strings) - Required - The search terms to count.
- **types** (array of strings) - Required - The data types to search within.
- **source** (string) - Optional - The data source(s) to query. Use 'all' for all sources.
- **wildcard** (boolean) - Optional - Whether to enable wildcard matching for terms.
- **dateFrom** (string) - Optional - The start date for the search range (YYYY-MM-DD).
- **dateTo** (string) - Optional - The end date for the search range (YYYY-MM-DD).
- **operator** (string) - Optional - The logical operator to combine terms ('AND' or 'OR'). Defaults to 'OR'.
- **regex** (boolean) - Optional - Whether to interpret terms as regular expressions.

### Request Example
```python
from keyscore import Client, CountRequest

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

# Basic count
try:
    count_req = CountRequest(
        terms=["example@domain.com", "test@company.com"],
        types=["email"],
        source="all"
    )
    count_result = client.count(count_req)
    print(f"Total results: {count_result.count}")
except APIError as e:
    print(f"Count failed: {e}")

# Count with date range and wildcards
count_req_advanced = CountRequest(
    terms=["*@example.com"],
    types=["email", "username"],
    source="source_name",
    wildcard=True,
    dateFrom="2024-01-01",
    dateTo="2024-12-31",
    operator="AND"
)
count_result = client.count(count_req_advanced)
print(f"Filtered results: {count_result.count}")
```

### Response
#### Success Response (200)
- **count** (integer) - The total number of results matching the criteria.

#### Response Example
```json
{
  "count": 15234
}
```
```

--------------------------------

### Initialize and use keyscore-py Client

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Demonstrates how to initialize the keyscore-py client with base URL and API key, then perform basic operations like checking API health, listing data sources, and searching for data.

```python
from keyscore import Client

# Initialize the client
client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

# Check API health
health = client.health()
print(f"API Status: {health.status}")

# Get available data sources
sources = client.sources()
print(f"Available sources: {len(sources)}")

# Search for data
results = client.search(query="example@domain.com", limit=10)
for result in results:
    print(f"Found: {result.value} from {result.source}")
```

--------------------------------

### Initialize keyscore API Client

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Demonstrates how to initialize the keyscore API client using an API key, environment variables, or custom session and timeout settings. Ensures proper authentication and configuration for API interactions.

```python
from keyscore import Client, APIError

# Initialize with API key
client = Client(
    base_url="https://api.keysco.re",
    api_key="your-api-key-here"
)

# Or read from environment variable
import os
api_key = os.environ.get('KEYSCORE_API_KEY', 'your-api-key-here')
client = Client(base_url="https://api.keysco.re", api_key=api_key)

# Custom timeout and session
import requests
session = requests.Session()
client = Client(
    base_url="https://api.keysco.re",
    api_key="your-api-key",
    session=session,
    timeout=30.0
)
```

--------------------------------

### Authenticate keyscore-py Client

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Shows two methods for authenticating the keyscore-py client: passing the API key directly during client initialization or setting it via an environment variable.

```python
# Method 1: Pass directly to client
client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

# Method 2: Set environment variable
import os
os.environ['KEYSCORE_API_KEY'] = 'your-api-key'
client = Client(base_url="https://api.keysco.re")
```

--------------------------------

### Client Initialization

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Initialize the keyscore API client with authentication credentials and configuration options. You can use an API key directly or read it from environment variables. Custom timeouts and sessions are also supported.

```APIDOC
## Client Initialization

### Description
Initialize the keyscore API client with authentication credentials and configuration options.

### Method
N/A (Client Initialization)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from keyscore import Client, APIError
import os
import requests

# Initialize with API key
client = Client(
    base_url="https://api.keysco.re",
    api_key="your-api-key-here"
)

# Or read from environment variable
api_key = os.environ.get('KEYSCORE_API_KEY', 'your-api-key-here')
client = Client(base_url="https://api.keysco.re", api_key=api_key)

# Custom timeout and session
session = requests.Session()
client = Client(
    base_url="https://api.keysco.re",
    api_key="your-api-key",
    session=session,
    timeout=30.0
)
```

### Response
N/A (Client Initialization)
```

--------------------------------

### List Available Data Sources

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Retrieves a list of available data sources and their capabilities.

```APIDOC
## GET /sources

### Description
Retrieves a list of available data sources and their capabilities.

### Method
GET

### Endpoint
/sources

### Parameters

#### Query Parameters
None

### Request Example
```python
sources = client.sources()
for source in sources:
    print(f"{source.name}: {source.description}")
    print(f"Types: {source.allowedTypes}")
```

### Response
#### Success Response (200)
- **name** (string) - The name of the data source.
- **description** (string) - A description of the data source.
- **allowedTypes** (array) - A list of data types supported by the source.

#### Response Example
```json
[
  {
    "name": "example_source",
    "description": "An example data source.",
    "allowedTypes": ["email", "domain"]
  }
]
```
```

--------------------------------

### Retrieve Machine Information by UUID with Python

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Fetches detailed system information for a specific machine using its UUID. Requires the keyscore library and an API key. Outputs various system metrics and a file tree if available.

```python
from keyscore import Client

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    machine_uuid = "550e8400-e29b-41d4-a716-446655440000"
    machine = client.machine_info(machine_uuid)

    print(f"Machine Information:")
    print(f"  Build ID: {machine.buildId}")
    print(f"  Computer Name: {machine.computerName}")
    print(f"  User Name: {machine.userName}")
    print(f"  Operating System: {machine.operationSystem}")
    print(f"  Processor: {machine.processor}")
    print(f"  Installed RAM: {machine.installedRAM}")
    print(f"  Graphics Card: {machine.graphicsCard}")
    print(f"  IP Address: {machine.ip}")
    print(f"  Country: {machine.country}")
    print(f"  System Language: {machine.systemLanguage}")
    print(f"  Time Zone: {machine.timeZone}")
    print(f"  Display Resolution: {machine.displayResolution}")
    print(f"  File Type: {machine.fileType}")

    if machine.fileTree:
        print(f"  File Tree ({len(machine.fileTree)} entries):")
        for file_path in machine.fileTree[:10]:  # Show first 10
            print(f"    {file_path}")

except APIError as e:
    print(f"Machine info lookup failed: {e}")
```

--------------------------------

### Handle API errors with keyscore-py

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Demonstrates how to use a try-except block to catch and handle potential API errors (APIError) or other unexpected exceptions when interacting with the keysco.re API.

```python
from keyscore import Client, APIError

try:
    client = Client(base_url="https://api.keysco.re", api_key="invalid-key")
    results = client.search("test")
except APIError as e:
    print(f"API Error: {e.message} (Status: {e.status_code})")
except Exception as e:
    print(f"Unexpected error: {e}")
```

--------------------------------

### Download a file by UUID using keyscore-py

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Downloads a file associated with a given UUID to a specified local file path.

```python
success = client.download("550e8400-e29b-41d4-a716-446655440000", "./downloaded_file")
if success:
    print("File downloaded successfully")
```

--------------------------------

### Download File

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Downloads a file associated with a given UUID to a specified local path.

```APIDOC
## POST /download/{uuid}

### Description
Downloads a file by its UUID to a specified local path.

### Method
POST

### Endpoint
/download/{uuid}

### Parameters

#### Path Parameters
- **uuid** (string) - Required - The UUID of the file to download.

#### Request Body
- **file_path** (string) - Required - The local path where the file should be saved.

### Request Example
```python
success = client.download("550e8400-e29b-41d4-a716-446655440000", "./downloaded_file")
if success:
    print("File downloaded successfully")
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the download was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### List Data Sources API

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Retrieve available data sources and their supported query types.

```APIDOC
## List Data Sources API

### Description
Retrieve available data sources and their supported query types.

### Method
GET

### Endpoint
`/sources`

### Parameters
N/A

### Request Example
```python
from keyscore import Client

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    sources_response = client.sources()
    for source_key, source_info in sources_response.sources.items():
        print(f"Source: {source_info.DisplayName} (Key: {source_info.Key})")
        print(f"  Allowed Types: {', '.join(source_info.AllowedTypes)}")
        print(f"  Sub-sources: {source_info.SubSources}")
        print(f"  Composite Of: {source_info.CompositeOf}")
        print()
except APIError as e:
    print(f"Failed to retrieve sources: {e}")
```

### Response
#### Success Response (200)
- **sources** (object) - A dictionary where keys are source identifiers and values are source information objects.
  - **Key** (string) - The unique identifier for the data source.
  - **DisplayName** (string) - The human-readable name of the data source.
  - **AllowedTypes** (array of strings) - A list of data types supported by this source.
  - **SubSources** (object) - Information about sub-sources, if any.
  - **CompositeOf** (array of strings) - Lists other sources this source is composed of.

#### Response Example
```json
{
  "sources": {
    "db_alpha": {
      "Key": "db_alpha",
      "DisplayName": "Database Alpha",
      "AllowedTypes": ["email", "hash", "ip", "username"],
      "SubSources": {"subA": "Sub Source A", "subB": "Sub Source B"},
      "CompositeOf": ["source1", "source2"]
    }
  }
}
```
```

--------------------------------

### List Available Data Sources

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Retrieves a list of all available data sources from the keysco.re API, including their display names, keys, allowed query types, sub-sources, and composite source information. Useful for understanding data availability.

```python
from keyscore import Client

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    sources_response = client.sources()

    for source_key, source_info in sources_response.sources.items():
        print(f"Source: {source_info.DisplayName} (Key: {source_info.Key})")
        print(f"  Allowed Types: {', '.join(source_info.AllowedTypes)}")
        print(f"  Sub-sources: {source_info.SubSources}")
        print(f"  Composite Of: {source_info.CompositeOf}")
        print()

    # Output example:
    # Source: Database Alpha (Key: db_alpha)
    #   Allowed Types: email, hash, ip, username
    #   Sub-sources: {'subA': 'Sub Source A', 'subB': 'Sub Source B'}
    #   Composite Of: ['source1', 'source2']
except APIError as e:
    print(f"Failed to retrieve sources: {e}")
```

--------------------------------

### Lookup information about a file hash using keyscore-py

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Queries the API to retrieve information associated with a given file hash, including its algorithm and associated filenames.

```python
hash_info = client.hash_lookup("d41d8cd98f00b204e9800998ecf8427e")
if hash_info:
    print(f"Hash: {hash_info.hash}")
    print(f"Algorithm: {hash_info.algorithm}")
    print(f"Filename: {hash_info.filename}")
```

--------------------------------

### Lookup information about an IP address using keyscore-py

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Fetches details about an IP address, such as its country and Internet Service Provider (ISP).

```python
ip_info = client.ip_lookup("8.8.8.8")
if ip_info:
    print(f"IP: {ip_info.ip}")
    print(f"Country: {ip_info.country}")
    print(f"ISP: {ip_info.isp}")
```

--------------------------------

### Machine Information Lookup

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Retrieves information about a machine using its UUID.

```APIDOC
## GET /machine/{uuid}

### Description
Retrieves information about a machine by its UUID.

### Method
GET

### Endpoint
/machine/{uuid}

### Parameters

#### Path Parameters
- **uuid** (string) - Required - The Universally Unique Identifier (UUID) of the machine.

### Request Example
```python
machine = client.machine_info("550e8400-e29b-41d4-a716-446655440000")
if machine:
    print(f"Computer: {machine.computerName}")
    print(f"OS: {machine.operationSystem}")
    print(f"User: {machine.userName}")
```

### Response
#### Success Response (200)
- **uuid** (string) - The machine's UUID.
- **computerName** (string) - The name of the computer.
- **operationSystem** (string) - The operating system of the machine.
- **userName** (string) - The current logged-in user's name.

#### Response Example
```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "computerName": "DESKTOP-ABCDEF",
  "operationSystem": "Windows 10",
  "userName": "JohnDoe"
}
```
```

--------------------------------

### Search data across sources with keyscore-py

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Performs a search query across specified data sources, with options for limiting results and pagination. Returns detailed search results.

```python
# Basic search
results = client.search("example@domain.com")

# Search with pagination
results = client.search("example@domain.com", limit=50, offset=100)

# Search specific sources
results = client.search("example@domain.com", sources=["source1"])

for result in results:
    print(f"Value: {result.value}")
    print(f"Source: {result.source}")
    print(f"Type: {result.type}")
    print(f"Date: {result.date}")
```

--------------------------------

### Search Data

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Searches for data across available sources based on a query, with options for source filtering and pagination.

```APIDOC
## GET /search

### Description
Searches for data across sources based on a query.

### Method
GET

### Endpoint
/search

### Parameters

#### Query Parameters
- **query** (string) - Required - The search query.
- **sources** (array of strings) - Optional - A list of source names to search within.
- **limit** (integer) - Optional - The maximum number of results to return (default: 100).
- **offset** (integer) - Optional - The number of results to skip (for pagination, default: 0).

### Request Example
```python
# Basic search
results = client.search("example@domain.com")

# Search with pagination
results = client.search("example@domain.com", limit=50, offset=100)

# Search specific sources
results = client.search("example@domain.com", sources=["source1"])

for result in results:
    print(f"Value: {result.value}")
    print(f"Source: {result.source}")
    print(f"Type: {result.type}")
    print(f"Date: {result.date}")
```

### Response
#### Success Response (200)
- **value** (string) - The data value found.
- **source** (string) - The source where the data was found.
- **type** (string) - The type of the data (e.g., "email", "domain").
- **date** (string) - The date the data was recorded or last seen.

#### Response Example
```json
[
  {
    "value": "example@domain.com",
    "source": "example_source",
    "type": "email",
    "date": "2023-10-27T10:00:00Z"
  }
]
```
```

--------------------------------

### File Hash Lookup

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Looks up information about a given file hash.

```APIDOC
## GET /hash/{hash_value}

### Description
Looks up information about a file hash.

### Method
GET

### Endpoint
/hash/{hash_value}

### Parameters

#### Path Parameters
- **hash_value** (string) - Required - The file hash to look up (e.g., MD5, SHA1, SHA256).

### Request Example
```python
hash_info = client.hash_lookup("d41d8cd98f00b204e9800998ecf8427e")
if hash_info:
    print(f"Hash: {hash_info.hash}")
    print(f"Algorithm: {hash_info.algorithm}")
    print(f"Filename: {hash_info.filename}")
```

### Response
#### Success Response (200)
- **hash** (string) - The file hash.
- **algorithm** (string) - The hashing algorithm used (e.g., "MD5", "SHA1", "SHA256").
- **filename** (string) - The name of the file associated with the hash, if known.

#### Response Example
```json
{
  "hash": "d41d8cd98f00b204e9800998ecf8427e",
  "algorithm": "MD5",
  "filename": "empty.txt"
}
```
```

--------------------------------

### Download Files by UUID with Python

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Downloads files associated with a given UUID, either the entire archive or a specific file. Requires the keyscore library and an API key. Saves downloaded content to a specified path.

```python
from keyscore import Client
import shutil

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    # Download entire archive
    download_uuid = "550e8400-e29b-41d4-a716-446655440000"
    download_result = client.download(download_uuid)

    print(f"Content Type: {download_result.content_type}")
    print(f"Content Length: {download_result.content_length} bytes")
    print(f"Content Disposition: {download_result.content_disposition}")

    # Save to disk
    output_path = "/tmp/downloaded_file.zip"
    with open(output_path, 'wb') as f:
        shutil.copyfileobj(download_result.body, f)
    print(f"File saved to: {output_path}")

    download_result.body.close()

    # Download specific file from archive
    specific_file = client.download(
        download_uuid,
        file_path="logs/browser_data.txt"
    )

    with open("/tmp/specific_file.txt", 'wb') as f:
        shutil.copyfileobj(specific_file.body, f)

    specific_file.body.close()

except APIError as e:
    print(f"Download failed: {e.message} (HTTP {e.status_code})")
```

--------------------------------

### Search Data with Keys P

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Searches across data sources with pagination and filtering. Requires API key and base URL. Returns search results including size, took time, results, and pagination info. Handles API errors.

```python
from keyscore import Client, SearchRequest

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    search_req = SearchRequest(
        terms=["user@example.com"],
        types=["email"],
        source="breach_database",
        pagesize=50,
        page=1
    )
    search_result = client.search(search_req)

    print(f"Found {search_result.size} results (took {search_result.took}ms)")

    if search_result.results:
        for source_key, records in search_result.results.items():
            print(f"\nSource: {source_key}")
            for record in records[:5]:  # Show first 5
                print(f"  Value: {record.get('value')}")
                print(f"  Type: {record.get('type')}")
                print(f"  Date: {record.get('date')}")
                print(f"  Metadata: {record.get('metadata', {})}")

    # Pagination info
    if search_result.pages:
        print(f"\nPagination: {search_result.pages}")

    # Output example:
    # Found 150 results (took 234ms)
    # Source: breach_database
    #   Value: user@example.com:password123
    #   Type: email
    #   Date: 2023-05-15
    #   Metadata: {'breach_name': 'Example Leak 2023'}
except APIError as e:
    print(f"Search failed: {e}")

# Advanced search with regex
advanced_req = SearchRequest(
    terms=["^admin.*@company\\.com$"],
    types=["email"],
    source="all_sources",
    regex=True,
    operator="OR",
    dateFrom="2024-01-01",
    pagesize=100
)
results = client.search(advanced_req)
```

--------------------------------

### IP Address Lookup

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Looks up information about a given IP address.

```APIDOC
## GET /ip/{ip_address}

### Description
Looks up information about an IP address.

### Method
GET

### Endpoint
/ip/{ip_address}

### Parameters

#### Path Parameters
- **ip_address** (string) - Required - The IP address to look up.

### Request Example
```python
ip_info = client.ip_lookup("8.8.8.8")
if ip_info:
    print(f"IP: {ip_info.ip}")
    print(f"Country: {ip_info.country}")
    print(f"ISP: {ip_info.isp}")
```

### Response
#### Success Response (200)
- **ip** (string) - The IP address.
- **country** (string) - The country associated with the IP address.
- **isp** (string) - The Internet Service Provider associated with the IP address.

#### Response Example
```json
{
  "ip": "8.8.8.8",
  "country": "United States",
  "isp": "Google LLC"
}
```
```

--------------------------------

### Hash Lookup with Keys P

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Looks up hash values to identify files or retrieve plaintexts. Requires API key and base URL. Accepts a list of hash terms (MD5, SHA1, SHA256). Returns hash records with type, plaintext, source, and first seen date. Handles API errors.

```python
from keyscore import Client, HashLookupRequest

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    hash_req = HashLookupRequest(terms=[
        "5d41402abc4b2a76b9719d911017c592",  # MD5
        "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d",  # SHA1
        "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"  # SHA256
    ])

    hash_result = client.hash_lookup(hash_req)

    print(f"Found {hash_result.size} hash records (took {hash_result.took}ms)")

    for hash_value, record in hash_result.results.items():
        print(f"\nHash: {record.hash}")
        print(f"Type: {record.type}")
        print(f"Plaintext: {record.plaintext}")
        print(f"Source: {record.source}")
        print(f"First Seen: {record.first_seen}")

    # Output example:
    # Found 2 hash records (took 89ms)
    # Hash: 5d41402abc4b2a76b9719d911017c592
    # Type: md5
    # Plaintext: hello
    # Source: rainbow_tables_v3
    # First Seen: 2023-03-12T14:22:01Z
except APIError as e:
    print(f"Hash lookup failed: {e}")
```

--------------------------------

### Handle API Errors with Python

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Demonstrates robust error handling for Keyscore API interactions. Catches APIError exceptions, providing status codes and messages, and includes specific checks for common HTTP error codes.

```python
from keyscore import Client, APIError, SearchRequest

client = Client(base_url="https://api.keysco.re", api_key="invalid-key")

try:
    search_req = SearchRequest(
        terms=["test@example.com"],
        types=["email"],
        source="test_source"
    )
    results = client.search(search_req)

except APIError as e:
    print(f"API Error occurred:")
    print(f"  Status Code: {e.status_code}")
    print(f"  Message: {e.message}")

    # Handle specific error codes
    if e.status_code == 401:
        print("Authentication failed. Check your API key.")
    elif e.status_code == 403:
        print("Access forbidden. Insufficient permissions.")
    elif e.status_code == 429:
        print("Rate limit exceeded. Please retry later.")
    elif e.status_code == 404:
        print("Resource not found.")
    elif e.status_code >= 500:
        print("Server error. Service may be temporarily unavailable.")

except Exception as e:
    print(f"Unexpected error: {type(e).__name__}: {e}")
```

--------------------------------

### IP Address Lookup with Keys P

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Retrieves geolocation and network information for IP addresses. Requires API key and base URL. Accepts a list of IP addresses. Returns detailed information including country, region, ISP, organization, AS, coordinates, timezone, and status. Handles IP lookup errors.

```python
from keyscore import Client, IPLookupRequest

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    ip_req = IPLookupRequest(terms=[
        "8.8.8.8",
        "1.1.1.1",
        "192.0.2.1"
    ])

    ip_result = client.ip_lookup(ip_req)

    print(f"Found {ip_result.size} IP records (took {ip_result.took}ms)")

    for ip_address, info in ip_result.results.items():
        print(f"\nIP: {ip_address}")
        print(f"Country: {info.country} ({info.countryCode})")
        print(f"Region: {info.regionName}, {info.city}")
        print(f"ISP: {info.isp}")
        print(f"Organization: {info.org}")
        print(f"AS: {info.as_}")
        print(f"Coordinates: {info.lat}, {info.lon}")
        print(f"Timezone: {info.timezone}")
        print(f"Status: {info.status}")

    # Check for errors
    if ip_result.errors:
        print("\nErrors:")
        for ip, error_msg in ip_result.errors.items():
            print(f"  {ip}: {error_msg}")

    # Output example:
    # Found 2 IP records (took 123ms)
    # IP: 8.8.8.8
    # Country: United States (US)
    # Region: California, Mountain View
    # ISP: Google LLC
    # Organization: Google Public DNS
    # AS: AS15169 Google LLC
    # Coordinates: 37.386, -122.0838
    # Timezone: America/Los_Angeles
    # Status: success
except APIError as e:
    print(f"IP lookup failed: {e}")
```

--------------------------------

### Detailed Count Breakdown

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Provides a detailed breakdown of result counts per source for a given query.

```APIDOC
## GET /count/detailed

### Description
Gets a detailed count breakdown by source for a given query.

### Method
GET

### Endpoint
/count/detailed

### Parameters

#### Query Parameters
- **query** (string) - Required - The search query.
- **sources** (array of strings) - Optional - A list of source names to filter the counts by.

### Request Example
```python
counts = client.count_detailed("example@domain.com")
for count in counts:
    print(f"{count.source}: {count.count} results")
```

### Response
#### Success Response (200)
- **source** (string) - The name of the data source.
- **count** (integer) - The number of results from this source.

#### Response Example
```json
[
  {
    "source": "source1",
    "count": 100
  },
  {
    "source": "source2",
    "count": 50
  }
]
```
```

--------------------------------

### Detailed Count of Results by Source

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Retrieves a detailed breakdown of result counts per data source for a given search query. Includes total count, processing time, and individual counts for each source. Supports regex filtering.

```python
from keyscore import Client, CountRequest

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    count_req = CountRequest(
        terms=["admin@example.com"],
        types=["email"],
        regex=False
    )
    detailed_count = client.count_detailed(count_req)

    print(f"Total: {detailed_count.total_count} (took {detailed_count.took}ms)")
    for source_name, count in detailed_count.counts.items():
        print(f"  {source_name}: {count} results")

    # Output example:
    # Total: 523 (took 145ms)
    #   breach_db_2023: 312 results
    #   leak_collection_v2: 189 results
    #   combo_lists: 22 results
except APIError as e:
    print(f"Detailed count failed: {e}")
```

--------------------------------

### API Health Check

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Checks the health status of the keysco.re API.

```APIDOC
## GET /health

### Description
Checks the health status of the API.

### Method
GET

### Endpoint
/health

### Parameters

#### Query Parameters
None

### Request Example
```python
health = client.health()
print(health.status)
```

### Response
#### Success Response (200)
- **status** (string) - The health status of the API (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Count results for a query in keyscore-py

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Counts the total number of results for a given query across all sources or a specified subset of sources.

```python
# Count across all sources
total = client.count("example@domain.com")
print(f"Total results: {total}")

# Count from specific sources
total = client.count("example@domain.com", sources=["source1", "source2"])
```

--------------------------------

### Health Check API

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Check the API service health status to verify connectivity and service availability.

```APIDOC
## Health Check API

### Description
Check the API service health status to verify connectivity and service availability.

### Method
GET

### Endpoint
`/health`

### Parameters
N/A

### Request Example
```python
from keyscore import Client

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    health = client.health()
    print(f"Status: {health.status}")
except APIError as e:
    print(f"Health check failed: {e.message} (HTTP {e.status_code})")
```

### Response
#### Success Response (200)
- **status** (string) - The health status of the API (e.g., "ok").

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Count Search Results

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Calculates the total number of results matching specified criteria across data sources. Supports basic term and type filtering, as well as advanced options like wildcards, date ranges, and operators.

```python
from keyscore import Client, CountRequest

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

# Basic count
try:
    count_req = CountRequest(
        terms=["example@domain.com", "test@company.com"],
        types=["email"],
        source="all"
    )
    count_result = client.count(count_req)
    print(f"Total results: {count_result.count}")
    # Output: Total results: 15234
except APIError as e:
    print(f"Count failed: {e}")

# Count with date range and wildcards
count_req_advanced = CountRequest(
    terms=["*@example.com"],
    types=["email", "username"],
    source="source_name",
    wildcard=True,
    dateFrom="2024-01-01",
    dateTo="2024-12-31",
    operator="AND"
)
count_result = client.count(count_req_advanced)
print(f"Filtered results: {count_result.count}")
```

--------------------------------

### Check API Service Health

Source: https://context7.com/keysco-re/keyscore-py/llms.txt

Provides a function to check the health status of the keysco.re API service. This helps verify connectivity and ensure the API is available for use. Handles potential API errors gracefully.

```python
from keyscore import Client

client = Client(base_url="https://api.keysco.re", api_key="your-api-key")

try:
    health = client.health()
    print(f"Status: {health.status}")
    # Output: Status: ok
except APIError as e:
    print(f"Health check failed: {e.message} (HTTP {e.status_code})")
```

--------------------------------

### Check keyscore-py API Health

Source: https://github.com/keysco-re/keyscore-py/blob/main/README.md

Retrieves the health status of the keysco.re API. This function returns a HealthResponse object containing the status.

```python
health = client.health()
print(health.status)  # "ok"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.