1. Coginiti Support Home
  2. API
  3. Execution API

Using Execution API

Revised

Introduction

With the Coginiti Execution API, users can effortlessly fetch data sets defined in the analytics catalog, bringing ease of use along with increased governance. It is designed to be compatible with popular data visualization and analysis tools such as PowerBI, Excel, and Jupyter Notebooks. It also could be used with popular orchestration tools such as Dagster or Kestra to trigger CoginitiScript publications or run data quality tests, ensuring both data consistency and reliability.

Base URL

All API URLs referenced in this documentation have the following base URL unless otherwise specified:

{hostname}/api/v1

 

Authentication

The following API requires authentication with a personal access token created in the Coginiti UI. Please follow the instructions here on how to create a personal access token.

 

Executing catalog assets to get a single result set

The given endpoint is used to execute a given script from the catalog and get a single result set. If the script produces several result sets, for example, when there are multiple SELECT statements present, only the first one will be executed and returned to the client.

Endpoint: {hostname}/api/v1/exec/script

Type of request: POST

Result format: JSON

Request example using curl application:

curl -X POST '{hostname}/api/v1/exec/script' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "path": "@Personal/Reports/performance",
  "params": {
    "start_date": "2012-01-01",
    "end_date": "2012-12-31"
  },
  "connection": {
    "name": "My Connection"
  }
}'

Body payload:

name description
path Absolute path to the catalog asset within the catalog. "@Personal", "@Shared", "@Project Hub", "@Legacy" are used to specify catalog namespace.
params Object with parameter names and their values that need to be passed into the script to be substituted instead of $params.
project_version Optional parameter for @Project Hub assets. Specifies the version of the published project to access. If not provided, the latest version will be used.
connection.name Name of the connection

 

For @Project Hub assets, the path should begin with @Project Hub/{project name}/ rather than the full absolute path within the @Project Hub workspace. For example, if a project named "sales_2025" is located at the absolute path @Project Hub/sales/reports/annual/sales_2025, the correct path to reference an asset of the project in an API call would be @Project Hub/sales_2025. Subsequent folders or files within that project would then follow, e.g., @Project Hub/sales_2025/path/to/asset/within/project

When working with @Project Hub assets, you can optionally specify a particular version of the published project using the project_version parameter. If not specified, the latest version will be used. For example, to execute a script from version "2.1.0" of a project:

curl -X POST '{hostname}/api/v1/exec/script' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "path": "@Project Hub/sales_2025/reports/quarterly",
  "project_version": "2.1.0",
  "params": {
    "quarter": "Q1",
    "year": "2025"
  },
  "connection": {
    "name": "My Connection"
  }
}'

 

Returns an object which represents result of the execution or an error otherwise.

name description
stats Statistics object.
stats.started_at Timestamp when execution started.
stats.finished_at Timestamp when execution is finished.
stats.duration_ms Duration of execution in milliseconds.
result Optional field. Contains result dataset if execution returns any data.

 

The dataset object has the following structure:

name description
columns A list of the names and types of the columns returned by the query.
data A list of the rows returned by the query request. Each row is itself a list that holds values of the columns in the row, in the order specified by the columns attribute.

 

The additional metadata associated with the given execution is passed as HTTP headers.

name description
X-Coginiti-Execution-Started-At Timestamp when execution started

 

Example of the response (including HTTP headers):

HTTP/2 200 
Date: Wed, 01 Nov 2023 10:03:17 GMT
Content-Type: application/json
X-Coginiti-Execution-Started-At: 2023-11-01T10:03:17.354799859Z
Vary: Accept-Encoding
Server: envoy

{
    "result": {
        "columns": [
            {
                "name": "col_1",
                "type": "INTEGER"
            },
            {
                "name": "col_2",
                "type": "STRING"
            }
        ],
        "data": [
            [
                1,
                "a"
            ],
            [
                2,
                "b"
            ]
        ]
    },
    "stats": {
        "started_at": "2023-08-10T15:06:57.581939751Z",
        "finished_at": "2023-08-10T15:07:57.581939751Z",
        "duration_ms":  1000
    }
}

 

Executing CoginitiScript block (available from version 24.4)

The given endpoint is used to execute a given CoginitiScript block from the catalog asset and get a single result set.

Endpoint: {hostname}/api/v1/exec/block

Type of request: POST

Result format: JSON

Request example using curl application:

curl -X POST '{hostname}/api/v1/exec/block' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "package": "@Personal/My Projects/demo/customers",
  "block_name": "CustomersWithEmailDomain",
  "args": {
    "domain": "coginiti.co"
  },
  "params": {},
  "connection": {
    "name": "My Connection"
  }
}'

Body payload:

name description
package Absolute path to the CoginitiScript package within the catalog. "@Personal", "@Shared", "@Project Hub", "@Legacy" are used to specify catalog namespace.
block_name Name of the block to execute within the specified package.
args Object with argument names and values to pass into the specified block.
params Object with parameter names and their values that need to be passed into the script to be substituted instead of $params.
project_version Optional parameter for @Project Hub assets. Specifies the version of the published project to access. If not provided, the latest version will be used.
connection.name Name of the connection

 

For @Project Hub assets, the path should begin with @Project Hub/{project name}/ rather than the full absolute path within the @Project Hub workspace. For example, if a project named "sales_2025" is located at the absolute path @Project Hub/sales/reports/annual/sales_2025, the correct path to reference the project in an API call would be @Project Hub/sales_2025. Subsequent folders within that project would then follow, e.g., @Project Hub/sales_2025/path/to/folder/within/project

When working with @Project Hub assets, you can optionally specify a particular version of the published project using the project_version parameter. If not specified, the latest version will be used. For example, to execute a block from version "1.2.0" of a project:

curl -X POST '{hostname}/api/v1/exec/block' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "package": "@Project Hub/sales_2025/analytics",
  "block_name": "MonthlyReport",
  "project_version": "1.2.0",
  "connection": {
    "name": "My Connection"
  }
}'

Returns an object that represents the result of the execution or an error otherwise.

name description
stats Statistics object.
stats.started_at Timestamp when execution started.
stats.finished_at Timestamp when execution is finished.
stats.duration_ms Duration of execution in milliseconds.
result Optional field. Contains result dataset if execution returns any data.

 

The dataset object has the following structure:

name description
columns A list of the names and types of the columns returned by the query.
data A list of the rows returned by the query request. Each row is itself a list that holds values of the columns in the row, in the order specified by the columns attribute.

 

The additional metadata associated with the given execution is passed as HTTP headers.

name description
X-Coginiti-Execution-Started-At Timestamp when execution started

 

Example of the response (including HTTP headers):

HTTP/2 200 
Date: Wed, 01 Nov 2023 10:03:17 GMT
Content-Type: application/json
X-Coginiti-Execution-Started-At: 2023-11-01T10:03:17.354799859Z
Vary: Accept-Encoding
Server: envoy

{
    "result": {
        "columns": [
            {
                "name": "col_1",
                "type": "INTEGER"
            },
            {
                "name": "col_2",
                "type": "STRING"
            }
        ],
        "data": [
            [
                1,
                "a"
            ],
            [
                2,
                "b"
            ]
        ]
    },
    "stats": {
        "started_at": "2023-08-10T15:06:57.581939751Z",
        "finished_at": "2023-08-10T15:07:57.581939751Z",
        "duration_ms":  1000
    }
}

Passing lists/maps as values to the block arguments

It is possible to pass not only literal values (numeric or string) into the block arguments but also composite types like lists and maps. To do this users have to use JSON list/object values.

Passing a list of values into "domains" block argument:

curl -X POST '{hostname}/api/v1/exec/block' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "package": "@Personal/My Projects/demo/customers",
  "block_name": "CustomersWithEmailDomain",
  "args": {
    "domains": ["coginiti.co", "gmail.com"]
  },
  "params": {},
  "connection": {
    "name": "My Connection"
  }
}'

Passing a map into "payment_fees" block argument:

curl -X POST '{hostname}/api/v1/exec/block' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "package": "@Personal/My Projects/demo/customers",
  "block_name": "CustomersWithEmailDomain",
  "args": {
    "payment_fees": {
      "credit_card": 0.25,
      "paypal": 0.3
    },
  },
  "params": {},
  "connection": {
    "name": "My Connection"
  }
}'

Specifying response format for single result

The Accept request HTTP header can be used by clients to specify in what format they want the result to be returned by the API. Supported options are:

 

Running CoginitiScript Tests via API (available from version 25.6)

The Coginiti Execution API supports executing CoginitiScript tests, allowing for automated data quality testing and continuous integration workflows. Tests can be executed individually or as part of test suites using the test.Run() functionality.

Executing Individual Test Blocks

Individual test blocks can be executed using the /api/v1/exec/block endpoint by specifying the test block name.

Request example for executing a single test:

curl -X POST '{hostname}/api/v1/exec/block' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "package": "@Personal/data_quality_tests",
  "block_name": "TestCustomerDataIntegrity",
  "connection": {
    "name": "My Connection"
  }
}'

Executing Test Suites with test.Run()

Test suites can be executed using scripts that contain test.Run() calls. This allows running multiple tests across different packages with configurable failure handling.

Request example for executing a test suite:

curl -X POST '{hostname}/api/v1/exec/script' \
  --header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
  "path": "@Personal/test_suites/nightly_tests",
  "connection": {
    "name": "My Connection"
  }
}'

Example of a test suite script content:

#+import "std/test"
#+import "@Personal/data_quality_tests"
#+import "@Personal/business_logic_tests"

{{
  test.Run(packages = [data_quality_tests, business_logic_tests], onFailure = test.Continue)
}}

Test Response Format

When executing tests, the API returns a specialized test report format instead of the standard result dataset. The response structure is:

name description
tests Array of individual test results.
tests[].package_name Full path to the package containing the test.
tests[].test_name Name of the individual test.
tests[].status Test result status: "PASSED" or "FAILED".
tests[].message Test result message or error details.
tests[].started_at Timestamp when the test started.
tests[].finished_at Timestamp when the test finished.
tests[].duration_ms Test execution duration in milliseconds.
stats Overall test execution statistics.
stats.tests Total number of tests executed.
stats.passed Number of tests that passed.
stats.failed Number of tests that failed.
stats.started_at Timestamp when test execution started.
stats.finished_at Timestamp when test execution finished.
stats.duration_ms Total test execution duration in milliseconds.

HTTP Status Codes for Test Execution

Important: Starting from version 25.6, the Coginiti API returns HTTP 200 OK for test executions even when some or all tests fail. This change ensures compatibility with CI/CD systems and allows clients to process test results programmatically without treating failed tests as HTTP errors.

The HTTP status codes for test execution are:

  • 200 OK: Test execution completed successfully (regardless of individual test pass/fail status)
  • 400 Bad Request: Invalid request parameters (missing package, connection, etc.)
  • 401 Unauthorized: Invalid or missing authentication token
  • 500 Internal Server Error: Execution engine or system error

To determine test success or failure, clients should examine the stats.failed field in the response body rather than relying on HTTP status codes.

Example Test Response

Example of a test execution response with mixed results:

HTTP/2 200
Date: Wed, 01 Nov 2023 10:03:17 GMT
Content-Type: application/json
X-Coginiti-Execution-Started-At: 2023-11-01T10:03:17.354799859Z
Vary: Accept-Encoding
Server: envoy

{
    "tests": [
        {
            "package_name": "@Personal/data_quality_tests",
            "test_name": "TestCustomerEmailFormat",
            "status": "PASSED",
            "message": "Test passed",
            "started_at": "2023-11-01T10:03:17.500Z",
            "finished_at": "2023-11-01T10:03:18.250Z",
            "duration_ms": 750
        },
        {
            "package_name": "@Personal/data_quality_tests",
            "test_name": "TestOrderIntegrity",
            "status": "FAILED",
            "message": "Test assertion failed: The test returned non-empty recordset:\norder_id | customer_id\n12345   | NULL",
            "started_at": "2023-11-01T10:03:18.250Z",
            "finished_at": "2023-11-01T10:03:19.100Z",
            "duration_ms": 850
        }
    ],
    "stats": {
        "tests": 2,
        "passed": 1,
        "failed": 1,
        "started_at": "2023-11-01T10:03:17.354Z",
        "finished_at": "2023-11-01T10:03:19.100Z",
        "duration_ms": 1746
    }
}

Integration with CI/CD Pipelines

The test execution API is designed for seamless integration with continuous integration and deployment pipelines. Here's an example of how to process test results in a CI script:

#!/bin/bash

# Execute tests via API
response=$(curl -s -X POST '{hostname}/api/v1/exec/script' \
  --header 'Authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "path": "@Personal/test_suites/ci_tests",
    "connection": {
      "name": "CI Connection"
    }
  }')

# Extract test statistics
failed_tests=$(echo "$response" | jq '.stats.failed')
total_tests=$(echo "$response" | jq '.stats.tests')

echo "Test Results: $((total_tests - failed_tests))/$total_tests passed"

# Exit with error code if any tests failed
if [ "$failed_tests" -gt 0 ]; then
  echo "$failed_tests test(s) failed"
  echo "$response" | jq '.tests[] | select(.status == "FAILED") | {test_name, message}'
  exit 1
else
  echo "All tests passed"
  exit 0
fi

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Articles in this section