---
title: "Core views"
slug: core
url: https://invertbio.com/docs/api/core
---

# Core views

The Core external API provides SQL access to bioprocess data in Invert. See [Authentication](/docs/api/authentication) for how to obtain an access token.

### Available Views

#### `v_bioprocesses`

*Note: parents of bioprocesses (aka experiments) have been moved to a separate table called `experiments`*

```bash
curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_bioprocesses LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/
```

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | String | Unique identifier for the bioprocess |
| `external_id` | String | An external identifier for the bioprocess |
| `name` | String | Name of the bioprocess |
| `parent_id` | String or null | Identifier of the parent bioprocess, if this is a child process |
| `scheduled_start_timestamp` | String or null | Scheduled start time (ISO 8601) |
| `scheduled_end_timestamp` | String or null | Scheduled end time (ISO 8601) |
| `start_timestamp` | String | Record start time (ISO 8601 with timezone) |
| `run_start_timestamp` | String or null | Start time of the bioprocess run |
| `run_end_timestamp` | String or null | End time of the bioprocess run |
| `end_timestamp` | String | Record end time (ISO 8601 with timezone) |
| `duration_ms` | Number | Duration of the bioprocess in milliseconds |
| `status` | String | Draft / Requested / Scheduled / In-progress / Completed |
| `qc` | Object | Quality control information: `{status, failure_mode}` |
| `data` | Array | List of data objects associated with the bioprocess |
| `events` | Array | List of events associated with the bioprocess |
| `induction_event` | Object or null | Information about the induction event |
| `attachments` | Array | List of attachments |
| `lineage` | Object or null | Lineage information |
| `last_updated_at` | String | Timestamp of the last update (ISO 8601) |

##### Common Event Types

**`DbObservationEvent`**

| Field | Type | Description |
|-------|------|-------------|
| `note` | String | Textual observation or comment |

**`DbAdditionEvent`**

| Field | Type | Description |
|-------|------|-------------|
| `lot_number` | String or null | Lot number of the added material |
| `reagent_name` | String or null | Name of the reagent added |
| `addition_type` | String | Type of addition (e.g., "Reagent Bolus", "Feed Start", "Induction", "Inoculation") |
| `volume` | Object | `{unit: string, value: number}` |

**`DbRemovalEvent`**

| Field | Type | Description |
|-------|------|-------------|
| `volume` | Object | `{unit: string, value: number}` |
| `lot_number` | String or null | Lot number associated with the removal |
| `sample_name` | String or null | Name or identifier of the sample removed |
| `removal_type` | String | Type of removal (e.g., "Sample", "Harvest") |

**`DbBioprocessPhaseEvent`**

| Field | Type | Description |
|-------|------|-------------|
| `phase` | String | Name of the bioprocess phase (e.g., "growth", "production") |
| `time_point` | String | Indicator of the phase timing (e.g., "start", "end") |

#### `v_timeseries`

```bash
curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_timeseries LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/
```

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | String | Unique identifier for the timeseries |
| `bioprocess_id` | String | Identifier of the associated bioprocess |
| `quantity_id` | String | Identifier of the associated quantity |
| `start_timestamp` | String | Start time (ISO 8601 with timezone) |
| `end_timestamp` | String | End time (ISO 8601 with timezone) |
| `duration_ms` | Number | Duration in milliseconds |
| `unit` | String | Unit of measurement |
| `statistics` | Object | Statistical summary (see below) |
| `last_updated_at` | String | Timestamp of last update (ISO 8601) |

**`statistics` object:**

| Field | Type | Description |
|-------|------|-------------|
| `max` | Number or null | Maximum value |
| `min` | Number or null | Minimum value |
| `sum` | Number | Sum of all values |
| `last` | Number or null | Last value |
| `count` | Number | Number of data points |
| `first` | Number or null | First value |
| `arithmetic_mean` | Number or null | Average of all values |
| `standard_deviation` | Number or null | Standard deviation |

#### `v_timeseries_data`

```bash
curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_timeseries_data LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/
```

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | String | Identifier of the timeseries this data point belongs to (ref to `v_timeseries.id`) |
| `timestamp` | String | Timestamp of the data point (ISO 8601) |
| `value` | Number or null | The recorded value at this timestamp |
| `data_item_id` | String or null | Optional identifier for the specific data item |

#### `v_quantities`

```bash
curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_quantities LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/
```

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | String | Unique identifier |
| `name` | String | Primary name of the quantity |
| `alternative_names` | Array of Strings | List of alternative names |
| `is_timeseries` | Boolean | Whether this quantity represents time series data |
| `data_type` | String | The data type |
| `default_unit` | String | The default display unit |
| `default_ingestion_unit` | String | The default unit used when ingesting data |
| `base_units` | Object | Base units object |
| `molar_mass` | Number or null | The molar mass, if applicable |
| `notes` | String or null | Additional notes |
| `last_updated_at` | String | Timestamp of last update (ISO 8601) |

#### `v_formulas`

```bash
curl -H "Authorization: Bearer <AUTH0_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_formulas LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/
```

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | String | Unique identifier |
| `name` | String | Name of the formula |
| `formula` | String | The actual formula/calculation |
| `log_scale` | Boolean | Whether to apply on a logarithmic scale |
| `disable_interpolation` | Boolean | Whether interpolation is disabled |
| `default_unit` | String or null | Default unit for the result |
| `run_phase` | String or null | Phase during which this formula is applicable |
| `notes` | String or null | Additional notes |
| `state` | String | Current state (e.g., "ready") |
| `last_updated_at` | String | Timestamp of last update (ISO 8601) |

**Example formula types:**
1. Simple references: `A`, `B`
2. Basic arithmetic: `(A+B+C)/3`, `A+B`
3. More complex: `(A*3)*B/100`
4. Time-based: `time_derivative_hours(A)`, `time_integral_hours(A*2)`
5. Advanced statistical: `log_linear_regression(A)`

#### `v_formula_results`

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | String | Unique identifier |
| `formula_id` | String | Identifier of the formula used |
| `bioprocess_id` | String | Identifier of the associated bioprocess |
| `unit` | String | Unit of measurement |
| `data` | Object or null | Single value result (if not a time series) |
| `timeseries` | Object or null | Time series data (if formula produces multiple values) |
| `timeseries_start_timestamp` | String | Start time of the time series |
| `timeseries_offset_ms` | Number | Time offset in milliseconds |
| `timeseries_statistics_min` | Number | Minimum value |
| `timeseries_statistics_max` | Number | Maximum value |
| `timeseries_statistics_arithmetic_mean` | Number | Arithmetic mean |
| `timeseries_statistics_standard_deviation` | Number | Standard deviation |
| `timeseries_statistics_sum` | Number | Sum of all values |
| `timeseries_statistics_first` | Number | First value |
| `timeseries_statistics_last` | Number | Last value |
| `timeseries_statistics_count` | Number | Number of data points |
| `last_updated_at` | String | Timestamp of last update |

When `timeseries` is not null: `{data: Array<Number>, times_ms: Array<Number>}`

#### `v_archived_records`

| Field Name | Type | Description |
|------------|------|-------------|
| `record_id` | String | Unique identifier for the archived record |
| `table_name` | String | Name of the source table |
| `archived_at` | String | Timestamp of archival (ISO 8601) |

#### `v_experiments`

| Field Name | Type | Description |
|------------|------|-------------|
| `id` | String | Unique identifier |
| `external_id` | String | An external identifier |
| `scheduled_start_timestamp` | String or null | Scheduled start time (ISO 8601) |
| `scheduled_end_timestamp` | String or null | Scheduled end time (ISO 8601) |
| `last_updated_at` | String | Timestamp of last update (ISO 8601) |

### Example Queries

#### Delta Loads

**Request data produced after a given date:**

```bash
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_bioprocesses WHERE last_updated_at > '"'"'2024-07-29'"'"' LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/
```

**Get timeseries updated since a bioprocess was last updated:**

```bash
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT * FROM v_timeseries WHERE last_updated_at > (SELECT MAX(last_updated_at) FROM v_bioprocesses)"}' \
 https://api.invertbio.com/external/v1/statements/
```

#### View Joins

**Get bioprocesses associated to a timeseries:**

```bash
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
 -H "Content-Type: application/json" \
 -X POST \
 -d '{"statement": "SELECT t.*, b.* FROM v_timeseries t LEFT JOIN v_bioprocesses b ON t.bioprocess_id = b.id LIMIT 1"}' \
 https://api.invertbio.com/external/v1/statements/
```

### Error States

**Timeouts**

Long running requests (>30 seconds) will be terminated and return a `504`. Modify your query to reduce/chunk the amount of data.

**SQL execution errors**

No data returned:

```json
{
  "data": [],
  "status": {
    "state": "success",
    "message": "Statement executed successfully, but returned no results."
  }
}
```

Non-existent view:

```json
{
  "data": [],
  "status": {
    "state": "error",
    "message": "relation \"v_non_existent_view\" does not exist"
  }
}
```

Syntax errors: JSON decode error — be careful about use of single vs double quotation marks.

**Unexpected exceptions**

```json
{
  "data": [],
  "status": {
    "state": "error",
    "message": "Error executing statement"
  }
}
```