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:

Go to User → Personal Tokens or Account → Account Tokens
Click Generate token
(Optional) Add a name/description for the token
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 which uses the same token generation process.

Client Initialization

The SDK uses ElementaryCloudClient to send data to Elementary Cloud:

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.

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:

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:

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:

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.

Table Assets

Test Decorators

Define data quality tests using decorators

Sending Results

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

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:

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.

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:

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 - Complete reference for all test decorators
Table Assets - Learn about table asset structure
Quickstart - Send your first test results to Elementary Cloud

​Getting Your API Credentials

​Generate an Access Token

​Security

​Client Initialization

​Test Context

​raise_on_error

​Test Decorators

​Context Manager Approach

​Supported Objects

Table Assets

Test Decorators

​Sending Results

​Sending results for multiple assets

​Error Handling

​Best Practices

​Next Steps

Getting Your API Credentials

Generate an Access Token

Security

Client Initialization

Test Context

`raise_on_error`

Test Decorators

Context Manager Approach

Supported Objects

Sending Results

Sending results for multiple assets

Error Handling

Best Practices

Next Steps