> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementary-data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

The Elementary Python SDK provides a simple API for sending data quality information to Elementary Cloud. This page provides an overview of the API structure and endpoints.

## Getting Your API Credentials

Before initializing the client, you need to obtain your API credentials from Elementary Cloud.

### Generate an Access Token

You can generate tokens directly from the Elementary UI:

1. Go to [User → Personal Tokens](https://app.elementary-data.com/settings/user-tokens) or [Account → Account Tokens](https://app.elementary-data.com/settings/account-tokens)
2. Click **Generate token**
3. (Optional) Add a name/description for the token
4. Copy the token and store it securely — **it is shown only once**

### Security

* **User tokens** are user-scoped bearer tokens and inherit your workspace permissions
* **Account tokens** are account-scoped bearer tokens with "Can View" permissions
* Treat tokens like passwords — do not share or commit them to version control
* Keep them secret, rotate regularly, and revoke immediately if compromised

For more details, see the [MCP Setup Guide](https://docs.elementary-data.com/cloud/mcp/setup-guide.md#1--generate-an-access-token) which uses the same token generation process.

## Client Initialization

The SDK uses `ElementaryCloudClient` to send data to Elementary Cloud:

```python theme={null}
from elementary_python_sdk.core.cloud.cloud_client import ElementaryCloudClient

client = ElementaryCloudClient(project_id, api_key, url)
```

Where:

* `project_id` is your Python project identifier (chosen by you, used to identify assets and tests belonging to this project across runs)
* `api_key` is your API token (generated from the steps above)
* `url` is the full SDK ingest endpoint URL (the Elementary team will provide you with this URL): `{base_url}/sdk-ingest/{env_id}/batch`
  * Example: `https://prod.api.elementary-data.com/sdk-ingest/a6b2425d-36e2-4e13-8458-9825688ca1f2/batch`
* `replace_existing_data` *(optional, default `False`)* — controls how each batch is handled on the cloud side:
  * `False` (default): each batch is **merged** into existing data. Assets and tests not present in a given call are left untouched. Assets and tests that have not been reported for approximately one month are removed automatically.
  * `True`: each batch is treated as the **complete set** of assets and tests for the project. Assets and tests previously sent but absent from the current batch are removed immediately on the cloud side.

> [!NOTE]
>
> Use `replace_existing_data=True` only if every run of this client submits the full set of assets and tests for the project. If your runs cover a subset of assets, leave this as `False` (the default) to avoid data loss.

## Test Context

Tests are run within an `elementary_test_context` which automatically captures test results:

```python theme={null}
from elementary_python_sdk.core.tests import elementary_test_context
from elementary_python_sdk.core.types.asset import TableAsset

asset = TableAsset(name="users", database_name="prod", schema_name="public", table_name="users")

with elementary_test_context(asset=asset) as ctx:
    # Run your tests here
    # Results are automatically captured in ctx
    client.send_to_cloud(ctx)
```

### `raise_on_error`

By default, `elementary_test_context` uses `raise_on_error=False`. This means that if a decorated test (or something inside the context) raises an exception, the SDK **captures it and records an `ERROR` execution** so you can still send results to Elementary Cloud without crashing your pipeline.

If you prefer **fail-fast** behavior (for example in CI), pass `raise_on_error=True` to re-raise exceptions after they are recorded:

```python theme={null}
with elementary_test_context(asset=asset, raise_on_error=True) as ctx:
    run_my_tests(df)
```

## Test Decorators

The SDK provides decorators to define tests:

* `@boolean_test` - For tests that return True/False (pass/fail)
* `@expected_range` - For tests that return numeric values within a range
* `@expected_values` - For tests that return values matching a list of expected values
* `@row_count` - For tests that return a Sized object (DataFrame, list, etc.) to check row count

## Context Manager Approach

You can also use context managers for inline tests:

```python theme={null}
with elementary_test_context(asset=asset) as ctx:
    # Using context managers
    with ctx.boolean_test(name="my_test", description="Inline test") as my_bool_test:
        my_bool_test.check_value(my_test_function())
    
    with ctx.expected_values_test(
        name="country_count",
        expected=[2, 3],
        allow_none=True,
        metadata={"my_metadata_field": "my_metadata_value"},
    ) as my_expected_values_test:
        # This will fail
        my_expected_values_test.check_value(5)
        # This will pass
        my_expected_values_test.check_value(3)
    
    with ctx.expected_range_test(
        name="age_range",
        min=18,
        max=50,
    ) as my_range_test:
        my_range_test.check_value(25.5)
    
    with ctx.row_count_test(
        name="row_count",
        min=1,
        max=1000,
    ) as my_row_count_test:
        my_row_count_test.check_value(users_df)  # Passes DataFrame, list, etc.
```

## Supported Objects

The SDK supports reporting table assets and test results.

> [card] [Table Assets](https://docs.elementary-data.com/python-sdk/api-reference/table-assets.md)
>
> Register tables and views in your data warehouse

> [card] [Test Decorators](https://docs.elementary-data.com/python-sdk/api-reference/test-decorators.md)
>
> Define data quality tests using decorators

## Sending Results

After running tests in a context, send results to Elementary Cloud:

```python theme={null}
client.send_to_cloud(ctx)
```

This automatically batches all test results from the context and sends them in a single request.

### Sending results for multiple assets

Each `elementary_test_context` holds one asset, so when your project monitors several tables you'll have one context per asset. Pass them together in a single `send_to_cloud` call instead of calling it once per asset:

```python theme={null}
with elementary_test_context(asset=users_asset) as users_ctx:
    test_unique_ids(users_df)
    test_average_age(users_df)

with elementary_test_context(asset=orders_asset) as orders_ctx:
    test_unique_ids(orders_df)
    test_row_count(orders_df)

client.send_to_cloud([users_ctx, orders_ctx])
```

This matters most when `replace_existing_data=True`: sending one context at a time would cause each call to remove assets reported by the previous call. Passing all contexts together ensures the full set of assets and tests reaches the cloud in one atomic batch.

> [!NOTE]
>
> If the same asset or test appears in more than one context, it is deduplicated — only the first occurrence is sent. All test executions are always kept, so the same test run against two contexts will produce two execution records.

## Error Handling

The SDK handles errors automatically, but you can wrap calls in try-except blocks:

```python theme={null}
try:
    client.send_to_cloud(ctx)
except Exception as e:
    print(f"Error sending results: {e}")
```

## Best Practices

* **One context per asset, one send call per project run** — Open one `elementary_test_context` per asset, then pass all contexts to a single `send_to_cloud` call.
* **Use descriptive test names** — Clear names help identify tests in the Elementary UI.
* **Include asset metadata** — Add descriptions, owners, tags, and dependencies to assets.

## Next Steps

* [Test Decorators](https://docs.elementary-data.com/python-sdk/api-reference/test-decorators.md) - Complete reference for all test decorators
* [Table Assets](https://docs.elementary-data.com/python-sdk/api-reference/table-assets.md) - Learn about table asset structure
* [Quickstart](https://docs.elementary-data.com/python-sdk/quickstart.md) - Send your first test results to Elementary Cloud


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.