Comotion Dash API Reference¶

Version 2 · October 2026

This document describes the HTTP APIs behind the Comotion Python SDK. It is for engineers who want to call the APIs directly, with curl, Python requests or any other HTTP client.

You should know HTTP and JSON. You do not need to know anything about how Comotion runs the service.

In examples, replace <org> with your org name and <zone> with your zone name. $TOKEN stands for a valid access token (see Authentication).

1. Overview¶

There are three APIs:

All three APIs:

• use HTTPS (TLS 1.2 or later) and JSON,
• need an Authorization: Bearer <access token> header on every request,
• get their tokens from your org's ComoAuth realm.

Org vs zone¶

An org is your Comotion Dash tenant. It has a main data lake.

A zone is a separate data area inside your org, with its own lake, its own permissions and its own API host. Use the Zone API for data in a zone. Use the Org API for the org's main lake. The two APIs have the same query and load endpoints. Only the Org API has no extra endpoints compared with the Zone API.

The data lake (data model v2)¶

• Lake tables hold your data. You add data to a lake table with a load.
• Every row has a service client (service_client_id). Your access is limited to the service clients your user has been given. See Roles and permissions.
• You read data with a query (SQL, Amazon Athena / Trino dialect).

Where the SDK fits¶

The Comotion Python SDK wraps these APIs. It handles login, token refresh, polling, file conversion and chunked uploads for you. Each endpoint below names the matching SDK call. If you work in Python, the SDK is usually the easiest option. Use the HTTP API directly from other languages, or when you need more control.

2. Hosts and regions¶

All paths in this document are relative to the base URL. For example, POST /query on the Org API is POST https://<org>.api.comodash.io/v2/query.

3. Authentication¶

3.1 Your ComoAuth realm¶

Each org has its own login realm on ComoAuth (an OpenID Connect provider):

The APIs only accept tokens whose issuer is your org's realm. A token from another org's realm is rejected.

3.2 Getting a token as a user (interactive)¶

The SDK's comotion authenticate command uses the OAuth 2.0 authorization code flow with PKCE:

1. It opens your browser at the authorization endpoint with client_id=comotion_cli, response_type=code, scope=openid, a PKCE code_challenge (S256) and a redirect to http://localhost:<random port>.
2. You log in. ComoAuth redirects back to the local port with a code.
3. The SDK swaps the code for tokens at the token endpoint (grant_type=authorization_code, the code_verifier and the same redirect_uri).
4. The SDK saves the refresh token in your operating system's credential manager (keyring). It does not save access tokens.
5. Each time it needs an access token, the SDK posts grant_type=refresh_token, client_id=comotion_cli and the saved refresh token to the token endpoint. It gets a new access token about 30 seconds before the current one expires.

If you already use the SDK, the simplest way to get a token for curl is:

from comotion.auth import Auth
print(Auth("<org>").get_access_token())

To do it yourself, refresh a token like this:

curl -s https://auth.comotion.us/auth/realms/<org>/protocol/openid-connect/token \
  -d grant_type=refresh_token \
  -d client_id=comotion_cli \
  -d refresh_token="$REFRESH_TOKEN" | jq -r .access_token

3.3 Getting a token as an application (machine to machine)¶

For scheduled jobs and services, Comotion can set up an application client for you with a client ID and client secret. It uses the OAuth 2.0 client credentials grant:

TOKEN=$(curl -s https://auth.comotion.us/auth/realms/<org>/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" | jq -r .access_token)

import requests

resp = requests.post(
    "https://auth.comotion.us/auth/realms/<org>/protocol/openid-connect/token",
    data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
resp.raise_for_status()
TOKEN = resp.json()["access_token"]

SDK equivalent: Auth("<org>", entity_type=Auth.APPLICATION, application_client_id=..., application_client_secret=...).

Ask Comotion support to create an application client. Its roles, scopes and service clients are set when it is created.

3.4 Token lifetime¶

Access tokens are short-lived. Read expires_in in the token response, or the exp claim in the token, and get a new token before it expires.

3.5 What the APIs check in the token¶

The service_client_id claim is a string in the form [12 13]: square brackets around service client IDs separated by spaces.

resource_access must contain an entry for the API's client (dash_api or dash_api_<zone>) listing your roles. See Roles and permissions.

Your Comotion administrator sets your audiences, scopes, roles and service clients. If a call fails with 401 or 403, decode your token (for example at a JWT debugger you trust, or with jq -R 'split(".")[1] | @base64d | fromjson') and compare it with the table above.

3.6 Common 401 and 403 causes¶

4. Roles and permissions¶

4.1 Service clients¶

Comotion uses service clients for row-level security. A service client usually represents one of your own clients or business units, and your access is limited to the service clients assigned to you.

Two IDs are special:

4.2 Roles¶

Roles are assigned per API: on dash_api for the Org API, and on dash_api_<zone> for each zone. A user can have different roles in different zones.

4.3 Capability matrix¶

¹ Only if the user's service_client_id claim includes 0. ² Public (901) rows only.

Notes:

• If a user has several roles, the capabilities add up.
• The load API also needs the load:write scope (or <zone>:load:write). Loads write through Comotion's load pipeline, not with your own permissions. The pipeline checks that every row belongs to a service client you can access.
• A user with no recognised role can only read their own query results. Every query that touches data fails.

4.4 How data scoping works in queries¶

Access is enforced on the stored data, which is split by service client. In practice:

• A query that reads data outside your service clients fails with a permissions error. It does not silently drop those rows.
• To read only what you may see, add your service client filter to the query, for example service_client_id IN ('12', '901') or 1=1 (all rows).
• Your query results are stored in a location tied to your user, roles and service clients. Only you can read them. If your roles or service clients change, you can no longer read results of queries you ran before the change.

4.5 Scopes per endpoint¶

5. Conventions¶

• Requests: send JSON bodies with Content-Type: application/json.
• Responses: JSON unless stated otherwise.
• Errors: most errors have the body {"message": "..."}. The identity endpoint also adds an error field. Where a message includes a request code (...please quote this code: <id>), send that code to support.
• Gateway errors: some errors come from the API gateway before your request reaches Comotion's code: 401 Unauthorized, 403 Forbidden (missing scope), 404 Not Found (unknown path), 413 (request too large) and a timeout error for requests that take longer than 30 seconds.
• Timeouts: every endpoint is designed to answer within seconds. Long-running work (queries, load commits, daily runs) runs in the background, and you poll for status.

Shell examples use these variables:

export ORG=<org>
export API=https://$ORG.api.comodash.io/v2
export TOKEN=...   # access token, see section 3

Python examples use:

import requests

ORG = "<org>"
API = f"https://{ORG}.api.comodash.io/v2"
TOKEN = "..."  # access token, see section 3
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

6. Queries¶

6.1 Lifecycle¶

POST /query ──► QUEUED ──► RUNNING ──► SUCCEEDED ──► GET /query/{id}/result (first 1,000 rows)
                                  │                 └► GET /query/{id}/csv    (full result)
                                  ├──► FAILED     (read status.stateChangeReason)
                                  └──► CANCELLED  (after DELETE /query/{id})

Polling: call GET /query/{query_id} every few seconds until the state is final. The SDK polls every 5 seconds. Do not poll more often than once a second.

6.2 POST /query: start a query¶

Starts a SQL query and returns its ID straight away.

• URL: https://<org>.api.comodash.io/v2/query
• Scope: query:write
• SDK equivalent: Query(config, query_text=...)

Request body

{"query": "select * from policies where service_client_id IN ('12', '901') limit 10"}

Response 202

{"queryId": "06ba1d95-8c4f-460c-90b3-bc68fddf2fde"}

Errors

QUERY_ID=$(curl -s -X POST "$API/query" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query": "select count(*) as n from policies"}' | jq -r .queryId)
echo "$QUERY_ID"

r = requests.post(f"{API}/query", headers=HEADERS,
                  json={"query": "select count(*) as n from policies"})
r.raise_for_status()
query_id = r.json()["queryId"]

6.3 GET /query/{query_id}: get query status¶

• URL: https://<org>.api.comodash.io/v2/query/06ba1d95-8c4f-460c-90b3-bc68fddf2fde
• Scope: query:read
• SDK equivalent: Query.get_query_info(), Query.state(), Query.wait_to_complete()

Response 200

{
  "query": "select count(*) as n from policies",
  "queryId": "06ba1d95-8c4f-460c-90b3-bc68fddf2fde",
  "statementType": "DML",
  "status": {
    "state": "SUCCEEDED",
    "submissionDateTime": "10-13-2026 09:58:01",
    "completionDateTime": "10-13-2026 09:58:04"
  }
}

Errors: 404 with An error occurred (InvalidRequestException): QueryExecution <id> was not found for an unknown ID. 500 for unexpected errors.

curl -s "$API/query/$QUERY_ID" -H "Authorization: Bearer $TOKEN" | jq .status

import time

while True:
    status = requests.get(f"{API}/query/{query_id}", headers=HEADERS).json()["status"]
    if status["state"] in ("SUCCEEDED", "FAILED", "CANCELLED"):
        break
    time.sleep(5)
if status["state"] != "SUCCEEDED":
    raise RuntimeError(status.get("stateChangeReason"))

6.4 DELETE /query/{query_id}: cancel a query¶

• URL: https://<org>.api.comodash.io/v2/query/06ba1d95-8c4f-460c-90b3-bc68fddf2fde
• Scope: query:write
• SDK equivalent: Query.stop()

Returns 200 with no body. The query moves to CANCELLED. Errors: 404 for an unknown ID, 500 for unexpected errors.

curl -s -X DELETE "$API/query/$QUERY_ID" -H "Authorization: Bearer $TOKEN" -o /dev/null -w "%{http_code}\n"

requests.delete(f"{API}/query/{query_id}", headers=HEADERS).raise_for_status()

6.5 GET /query/{query_id}/result: first page of results¶

Returns up to 1,000 rows of a SUCCEEDED query as JSON. On this page the first row holds the column names. Every value is a string.

This endpoint returns only the first page. If the response contains nextToken, there are more rows. Use the CSV download for the full result.

• URL: https://<org>.api.comodash.io/v2/query/06ba1d95-8c4f-460c-90b3-bc68fddf2fde/result
• Scope: query:read
• SDK equivalent: none (the SDK uses the CSV download).

Response 200

{
  "resultSet": {
    "Rows": [
      {"Data": [{"VarCharValue": "policy_number"}, {"VarCharValue": "face_amount"}]},
      {"Data": [{"VarCharValue": "P0001"}, {"VarCharValue": "20000"}]}
    ],
    "ResultSetMetadata": {
      "ColumnInfo": [
        {"Name": "policy_number", "Label": "policy_number", "Type": "varchar", "Precision": 2147483647, "Scale": 0, "Nullable": "UNKNOWN", "CaseSensitive": true},
        {"Name": "face_amount", "Label": "face_amount", "Type": "bigint", "Precision": 19, "Scale": 0, "Nullable": "UNKNOWN", "CaseSensitive": false}
      ]
    }
  }
}

Errors: 404 for an unknown ID. 403 permission messages as for POST /query. 500 for unexpected errors.

page = requests.get(f"{API}/query/{query_id}/result", headers=HEADERS).json()
rows = [[c.get("VarCharValue") for c in r["Data"]] for r in page["resultSet"]["Rows"]]
header, data = rows[0], rows[1:]

6.6 GET /query/{query_id}/csv: download the full result¶

Redirects to a pre-signed HTTPS link for the full result as a CSV file. The query must be SUCCEEDED.

• URL: https://<org>.api.comodash.io/v2/query/06ba1d95-8c4f-460c-90b3-bc68fddf2fde/csv
• Scope: query:read
• SDK equivalent: Query.download_csv(path), Query.get_csv_for_streaming()

Response 302

• Location header: the pre-signed link.
• Body: {"location": "<the same link>"}.

Important:

• Do not send your Authorization header to the pre-signed link. The link carries its own signature, and the storage service rejects requests that have both. curl (7.58 and later) and Python requests drop the header when a redirect changes host.
• The link expires quickly (at most 15 minutes). Start the download straight away. If it expires, call this endpoint again.
• The CSV has a header row. Values are quoted.

Errors: any problem, including a query that is not SUCCEEDED or does not exist, returns 500 {"message": "Internal Server Error"}. Check the query status first.

curl -s -L "$API/query/$QUERY_ID/csv" -H "Authorization: Bearer $TOKEN" -o result.csv

r = requests.get(f"{API}/query/{query_id}/csv", headers=HEADERS,
                 allow_redirects=False)
r.raise_for_status()                     # 302
with requests.get(r.headers["Location"], stream=True) as dl:   # no auth header
    dl.raise_for_status()
    with open("result.csv", "wb") as f:
        for chunk in dl.iter_content(1024 * 1024):
            f.write(chunk)

7. Loads¶

A load adds rows to one lake table. Four steps:

1. Create the load with POST /load. You get a loadId.
2. Upload one or more parquet files with POST /load/{load_id}/file, then upload each file to the link it returns.
3. Commit the load with checksums using POST /load/{load_id}/commit.
4. Poll GET /load/{load_id} until SUCCESS or FAIL.

Either all rows are added or none. Only you can see or change your loads.

7.1 Load status¶

Poll every 5 seconds while the status is PROCESSING.

7.2 POST /load: create a load¶

URL: POST https://<org>.api.comodash.io/v2/load | Scope: load:write

SDK equivalent: Load(config, load_type="APPEND_ONLY", table_name=...)

Request fields

Response 202

{"loadId": "20261013095801_355d42f6_0684_4b8f_b274_225bf7237494"}

Key errors: 400 MissingParameterError for missing fields; 400 InvalidParameterError: invalid load_type parameter (only APPEND_ONLY is accepted); 400 InvalidParameterError: table_name - Value should be in lowercase and contain only lowercase letters and underscores.

load_as_service_client_id is not verified here. If you cannot access that service client, the commit fails later with ErrorType: PermissionsError.

LOAD_ID=$(curl -s -X POST "$API/load" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"load_type":"APPEND_ONLY","table_name":"policies","load_as_service_client_id":"12"}' \
  | jq -r .loadId)

r = requests.post(f"{API}/load", headers=HEADERS, json={
    "load_type": "APPEND_ONLY", "table_name": "policies",
    "load_as_service_client_id": "12",
})
r.raise_for_status()
load_id = r.json()["loadId"]

7.3 POST /load/{load_id}/file: upload a file¶

Returns a pre-signed S3 URL and temporary credentials for uploading one parquet file. Call once per file. The credentials expire after 1 hour.

URL: POST https://<org>.api.comodash.io/v2/load/{load_id}/file | Scope: load:write

SDK equivalent: Load.upload_file(data, ...) or Load.upload_df(df, ...)

Optional request body field

Response 200

File requirements (enforced at commit time, not during upload):

• Must be a valid parquet file.
• Column names: only lowercase letters, numbers and underscores.
• If load_as_service_client_id was not given in POST /load, files must include a service_client_id column.
• If load_as_service_client_id was given, files must not include a service_client_id column.

Key errors: 400 InvalidParameterError: file_key - ... for a bad file_key; 404 NotFound: load_id does not exist for this user. for an unknown load ID.

7.4 POST /load/{load_id}/commit: commit the load¶

Starts the load pipeline. The status becomes PROCESSING. The load ID is the pipeline execution name, so calling this endpoint twice returns 400 InvalidParameter: Load Already Committed.

URL: POST https://<org>.api.comodash.io/v2/load/{load_id}/commit | Scope: load:write

SDK equivalent: Load.commit(check_sum={...})

Request body

{"check_sum": {"count(*)": 50000, "sum(face_amount)": 9876543210}}

check_sum is required and must have at least one entry. Keys are SQL aggregate expressions run over all uploaded rows. Values are what you expect. Accepts string, integer or float values.

Response 202: {"message": "Commit initiated."}

Key errors

curl -s -X POST "$API/load/$LOAD_ID/commit" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"check_sum": {"count(*)": 50000}}'

requests.post(f"{API}/load/{load_id}/commit", headers=HEADERS,
              json={"check_sum": {"count(*)": 50000}}).raise_for_status()

7.5 GET /load/{load_id}: get load status¶

URL: GET https://<org>.api.comodash.io/v2/load/{load_id} | Scope: load:read

SDK equivalent: Load.wait_to_complete(), Load.get_load_info()

Response 200

ErrorType values

{
  "LoadStatus": "FAIL",
  "ErrorType": "CheckSumError",
  "ErrorMessages": [
    {
      "CheckResult": "FAIL",
      "ErrorType": "CheckSumError",
      "ErrorMessage": "Checksum count(*) was expecting 50001 and got 50000"
    }
  ]
}

import time

while True:
    r = requests.get(f"{API}/load/{load_id}", headers=HEADERS).json()
    print(r["LoadStatus"])
    if r["LoadStatus"] not in ("OPEN", "PROCESSING"):
        break
    time.sleep(5)
if r["LoadStatus"] != "SUCCESS":
    raise RuntimeError(r.get("ErrorMessages"))

7.6 What happens after commit (pipeline overview)¶

1. Files are collected and validated (parquet format and column names).
2. A temporary Athena table is created from all uploaded files.
3. Service client rules are enforced per row.
4. Checksums are calculated and compared with your expected values.
5. The lake table is created (if new) or columns are matched (if it exists). Column types must match.
6. Rows are inserted. Every row gets a dash$load_id column. The table is partitioned by service_client_id, dash$load_id and any extra partitions you requested.

8. DailyRun API¶

The DailyRun API controls and monitors the nightly ETL pipeline that refreshes your org's lake. It is accessed at api.{orgname}.{region-domain}/superset.

Note — The DailyRun enabled flag only controls the scheduled nightly kickoff. You can always trigger a manual run via POST /dailyRun/start_execution regardless of the flag.

8.1 GET /dailyRun/dailyRun_enabled¶

Returns whether the scheduled nightly ETL run is enabled for this org.

Required scope: dailyrun:enabled:read

Request¶

GET https://api.{orgname}.{region-domain}/superset/dailyRun/dailyRun_enabled
Authorization: Bearer {access_token}

Responses¶

200 example

{ "dailyRun": true }

8.2 POST /dailyRun/dailyRun_enabled¶

Enables or disables the scheduled nightly ETL run.

Required scope: dailyrun:enabled:write

Request¶

POST https://api.{orgname}.{region-domain}/superset/dailyRun/dailyRun_enabled
Authorization: Bearer {access_token}
Content-Type: application/json

Example request body

{ "dailyRun": true }

Responses¶

200 example

{ "dailyRun": true }

8.3 GET /dailyRun/execution_status¶

Returns execution records for this org's nightly pipeline.

Required scope: dailyrun:execution:read

Request¶

GET https://api.{orgname}.{region-domain}/superset/dailyRun/execution_status
Authorization: Bearer {access_token}

Query parameters¶

mode values¶

Execution object fields¶

Responses¶

200 — mode=list

{
  "executions": [
    {
      "name": "DailyScheduledETL_<org>_20250401T020000Z",
      "status": "SUCCEEDED",
      "startDate": "2025-04-01T02:00:00.000000+00:00",
      "stopDate":  "2025-04-01T02:14:37.000000+00:00"
    }
  ]
}

200 — mode=latest

{
  "name": "DailyScheduledETL_<org>_20250401T020000Z",
  "status": "SUCCEEDED",
  "startDate": "2025-04-01T02:00:00.000000+00:00",
  "stopDate":  "2025-04-01T02:14:37.000000+00:00"
}

(Returns null body when no executions exist.)

200 — mode=last_successful (none found)

{ "message": "No successful Daily ETL executions found." }

400 — invalid mode

{
  "message": "mode is not valid, mode should be one of: list, latest, last_successful"
}

8.4 POST /dailyRun/start_execution¶

Manually starts a new pipeline execution for this org. The pipeline input is constructed automatically from your org's configuration — you do not supply it.

Required scope: dailyrun:execution:write

Request¶

POST https://api.{orgname}.{region-domain}/superset/dailyRun/start_execution
Authorization: Bearer {access_token}

No request body required.

Responses¶

200 success body

{
  "message": "Daily ETL pipeline execution started.",
  "started": true,
  "executionArn": "arn:aws:states:eu-west-1:...:execution:DailyETLPipeline:DailyScheduledETL_<org>_20250401T020000Z",
  "startDate": "2025-04-01T02:00:00.000000+00:00",
  "executionName": "DailyScheduledETL_<org>_20250401T020000Z",
  "stateMachineArn": "arn:aws:states:eu-west-1:...:stateMachine:DailyETLPipeline"
}

executionArn and stateMachineArn are included for reference; treat them as opaque strings. They are not needed for normal polling — use GET /dailyRun/execution_status?mode=latest to track progress.

409 conflict body

{
  "message": "Daily ETL pipeline is already running for this client; no execution started.",
  "started": false,
  "executionName": null,
  "runningExecution": {
    "name": "DailyScheduledETL_<org>_20250401T020000Z",
    "status": "RUNNING",
    "startDate": "2025-04-01T02:00:00.000000+00:00"
  },
  "stateMachineArn": "arn:aws:states:eu-west-1:...:stateMachine:DailyETLPipeline"
}

Typical polling flow¶

POST /dailyRun/start_execution
  → 200 { "executionName": "DailyScheduledETL_<org>_..." }

Loop:
  GET /dailyRun/execution_status?mode=latest
    → { "status": "RUNNING", ... }   ← keep polling
    → { "status": "SUCCEEDED", ... } ← done
    → { "status": "FAILED", ... }    ← check logs

9. Zone API¶

A zone is a separate data area inside your org with its own lake, its own AWS account, and its own API host. The Zone API has the same query and load endpoints as the Org API, but with the following differences.

11.1 Host¶

https://{zonename}.{orgname}.api.{region-domain}/v2/

Example: https://<zone>.<org>.api.comodash.io/v2/

11.2 Audience and scopes¶

Zone scopes follow the pattern {zonename}:{action}. Examples for a zone named <zone>:

You must request a token with the correct audience (dash_api_<zone>) and scope against the same ComoAuth realm (https://auth.comotion.us/auth/realms/{orgname}).

11.3 Available endpoints¶

The Zone API exposes only query and load endpoints:

11.4 Base path¶

The Zone API base path is /v2 (not /v1 as on the Org API).

10. Error reference¶

All error responses use the shape:

{ "message": "Human-readable description" }

Where the error originates from a handler validation step it may also include:

{ "message": "MissingParameterError: load_type parameter missing from request." }

or

{ "message": "InvalidParameterError: invalid load_type parameter" }

HTTP status codes¶

Load error types (recap)¶