🚀 Run an Analysis on the NCA Engine
Once a file is uploaded you can run an NCA Engine Execution against it.
In general, you can follow the flow of:
- Uploading a file
- Then run an execute action right away
Or
- Upload one or more files
- Run executions at a later date and time. see Listing Files
Tip
No matter which flow you take, the execution portion is the same and in this section, we'll take a deeper dive into how to run an execution.
Route
See Workflow in the API routes reference (Send Analysis to Queue).
Payload
The queue request body has a small envelope plus one workflow-config block that determines the workflow type:
| Name | Required | Description |
|---|---|---|
fileId | one of | Entry point for a file-based run (analysis, data-cleaning): the id of the uploaded file (returned by the upload request as data.fileId). |
parentExecutionId | one of | Entry point for a chained run (custom calculations, plots, tables, reports): the execution this run builds on. Use this instead of fileId. |
name | no | A human-friendly name for the execution. |
| workflow-config block | yes | One of calculation (NCA analysis), data_cleaning, custom_calculations, custom_plots, custom_tables, or custom_reports — the block you include determines the workflow type. Exception: custom_plots and custom_tables may be sent together in one body to run simultaneously. |
metadata | no | Caller-defined data stored as-is with the execution (e.g. project id, tags). |
Tip
You don't need to hand-author the config block. The web app's wizard produces it for you, and the interactive API reference lets you view and try the full payload for each workflow type.
Inside data_cleaning.rules and custom_calculations.calculations, each item is self-describing by its type — the keys it accepts (and the column names / values it references) depend on that rule/calculation type and your input data. The examples below show representative shapes.
Example: NCA Analysis
A full calculation (NCA) queue body — entry point is fileId. Generated from our OpenAPI specification, so it stays current with the API.
Example: Data Cleaning
A dataCleaning body — entry point is fileId. The rules[] array is applied in order; each rule is typed (e.g. add_column, find_replace, conversion, filter, blq). Rules can be composite: a grouping rule carries its own nested rules[] that run per group. The example below is trimmed to show the key patterns.
Example: Custom Calculations
A customCalculations queue body — chains off a prior run via parentExecutionId. Each entry in calculations[] is typed (here, ratio).
Example: Custom Plots & Tables
A post-processing body chaining off a prior run via parentExecutionId. customPlots and customTables can each be sent on their own, or together in one body — a distinctive capability that lets plots and tables run simultaneously (shown below). Each entry in plots[] / tables[] is typed (e.g. individual_linear, summary_pk_parameters).
Example: Custom Reports
A customReport body — chains off a prior run via parentExecutionId. It assembles a document from a template plus sections.
Tip
If you list a section (e.g. tables or plots) without defining exactly which items to include, the report builder auto-populates it from the parent execution's available outputs. So the minimal body below produces a full report.
Note
You can send request fields in camelCase or snake_case — the API accepts either and normalizes to snake_case internally. Responses come back in camelCase to match the web app.
Response
The analysis is accepted onto the workflow queue and the response returns data.executionId and data.status (queued, or throttled with a delaySeconds when admission is delayed). Use the executionId to poll for status.
Example with 🐍 Python
Example of how an execution is launched.