View Model

Field	Type	Description
`mapping_policy_revision`	`number \| null`
`mapping_policy_nullable_inputs`	`string[]`
`mapping_policy_fallback_groups`	`string[][]`
`mapping_policy_allow_drops`	`boolean`
`mapping_policy_output_bindings`	`Record<string, string[]>`
`mapping_generation`	`number`
`object`	`"view"`
`id`	`string`	Unique identifier, prefixed with `viw_`.
`team_id`	`string`
`project_id`	`string`
`collection_id`	`string \| null`	The collection this view reads from; null when it reads from another view.
`collection_name`	`string \| null`	Display name of that collection.
`parent_view_id`	`string \| null`	The view this one is derived from; null when it reads from a collection.
`parent_view_name`	`string \| null`	Display name of that view.
`view_mode`	`string`	Where the view's records come from: a collection, another view, or a join of several.
`transform_mode`	`ViewTransformMode`	Whether transform scripts are generated for new schema versions or written by you.
`name`	`string`
`hint`	`string \| null`	Plain-language guidance the generator uses when it writes transform scripts.
`output_schema`	`ViewOutputField[]`	The fields this view's records contain.
`status`	`ViewStatus`	Whether the view is producing records, still being set up, or failed.
`error_message`	`string \| null`	Why the view failed, when its status is `error`.
`waiting_shapes_count`	`number`	How many event shapes arrived that no transform serves yet. Their records are stored and catch up automatically once a script covers them; the shapes are listed by the view's deferrals endpoint.
`deleted_at`	`ISODateString \| null`	When the view is scheduled to be deleted; null when it is not.
`created_at`	`ISODateString`
`updated_at`	`ISODateString`
`join_base_view_id`	`string \| null`	The base view on a join view; null on other views.
`join_base_view_name`	`string \| null`
`join_status`	`ViewJoinStatus \| null`
`join_backfill_cutoff_at`	`ISODateString \| null`	Records after this instant are joined live.
`join_live_started_at`	`ISODateString \| null`	When the join started matching new records.
`join_lookup_progress`	`LookupProgress \| null`	Lookup progress keyed by clause alias.
`join_base_file_count`	`number \| null`	Number of base-view files to backfill.
`join_base_files_done`	`number \| null`	Number of base-view files already processed.
`join_error_message`	`string \| null`
`join_created_at`	`ISODateString \| null`
`join_updated_at`	`ISODateString \| null`
`joins`	`ViewJoinClause[]`	The views joined onto the base view, on a join view.
`metrics_count`	`number`	How many metrics read from this view.
`derived_views_count`	`number`	How many views are derived from this one.
`join_views_count`	`number`	How many join views use this one as an input.
`transform_count`	`number`	How many transforms this view has.
`drains_count`	`number`	How many drains forward this view's records.
`backfill_file_count`	`number`	How many files every transform on this view has to process between them.
`backfill_files_done`	`number`	How many of those files they have processed.
`backfill_started_at`	`ISODateString \| null`	When the earliest of those backfills began. This is the earliest start across the whole view, which is what a throughput estimate has to measure elapsed time from.

View Transform Model

Field	Type	Description
`object`	`"view_transform"`
`id`	`string`	Unique identifier, prefixed with `vtr_`.
`view_id`	`string`	The view this transform produces records for.
`transform_script`	`string \| null`	The TGL script that maps incoming records onto the view's fields; null until one is written.
`status`	`ViewTransformStatus`	Whether the transform is running, waiting for a script, or failed.
`error_message`	`string \| null`	Why the transform failed, when its status is `error`.
`tgl_retry_count`	`number`	How many times script generation has been retried for this transform.
`max_read_depth`	`number \| null`	How many levels deep into a record the script reads.
`evidence_notice`	`ViewEvidenceNotice \| null`	Set when a path this mapping read as empty at authoring time has since carried a value with a type, listing those paths as `L<depth>:<path>` read keys. Rows keep flowing; re-author the mapping to use the new column. Cleared when a new script is generated.
`backfill_status`	`ViewTransformBackfillStatus`	Whether existing records have been reprocessed through this transform yet.
`backfill_cutoff_at`	`ISODateString \| null`	Records after this time are handled live rather than by the backfill.
`backfill_start_at`	`ISODateString \| null`	The earliest record the backfill will reach.
`backfill_started_at`	`ISODateString \| null`	When the backfill began.
`backfill_completed_at`	`ISODateString \| null`	When the backfill finished.
`backfill_file_count`	`number`	How many files the backfill has to process.
`backfill_files_done`	`number`	How many of those files it has processed.
`backfill_error`	`string \| null`	Why the backfill failed, when it did.
`assignments`	`ViewTransformAssignment[]`	Backfill progress for each source schema version this transform covers.
`created_at`	`ISODateString`
`updated_at`	`ISODateString`

View Version Model

Field	Type	Description
`object`	`"view_version"`
`id`	`string`	Unique identifier, prefixed with `vta_`.
`view_id`	`string`
`version`	`number`	The source schema version this row covers. Versions rise as the source's shape changes.
`transform_id`	`string`	The transform whose script serves this version. Several versions can share one transform.
`status`	`ViewTransformStatus`	Whether the transform is running, waiting for a script, or failed.
`error_message`	`string \| null`	Why the transform failed, when its status is `error`.
`evidence_notice`	`ViewEvidenceNotice \| null`	Set when a path the serving script read as empty at authoring time has since carried a value with a type; lists those paths as `L<depth>:<path>` read keys. Re-author the mapping to use the new column. Cleared when a new script is generated.
`script_hash`	`string \| null`	Identity of the script text. Versions sharing a hash run the identical script.
`script`	`string \| null`	The TGL script serving this version; null until one is written.
`backfill_status`	`ViewTransformBackfillStatus`	Whether the records already on this schema version have been reprocessed yet.
`backfill_start_at`	`ISODateString \| null`	The earliest record the backfill will reach.
`backfill_started_at`	`ISODateString \| null`	When the backfill began.
`backfill_completed_at`	`ISODateString \| null`	When the backfill finished.
`backfill_file_count`	`number`	How many files the backfill has to process for this version.
`backfill_files_done`	`number`	How many of those files it has processed.
`backfill_error`	`string \| null`	Why the backfill failed, when it did.
`created_at`	`ISODateString`	When the view started covering this schema version.
`updated_at`	`ISODateString`	When the transform serving this version last changed.

Waiting Shape Model

Field	Type	Description
`episode`	`number`
`observation_count`	`string \| null`
`retained_rows`	`number`
`first_observed_at`	`ISODateString \| null`
`last_observed_at`	`ISODateString \| null`
`next_action_at`	`ISODateString \| null`
`hint_question`	`string \| null`
`hint_reason`	`string \| null`
`hint_paths`	`string[]`
`hint_requested_at`	`string \| null`
`hint_mapping_generation`	`number \| null`
`exclusion_reason`	`string \| null`
`excluded_at`	`ISODateString \| null`
`transform_id`	`string \| null`
`object`	`"view_shape_deferral"`
`id`	`string`	Unique identifier, prefixed with `vsd_`.
`view_id`	`string`
`full_signature`	`string`	The typed signature identifying the event shape.
`event_count`	`number`	Roughly how many events of the shape arrived while it was waiting; retries can count an event more than once.
`first_event_at`	`ISODateString \| null`	The earliest event time seen for the shape. Completeness reporting pins to this instant.
`first_deferred_at`	`ISODateString`
`last_deferred_at`	`ISODateString`
`resolved_at`	`ISODateString \| null`	When the shape became served; null while it is still waiting.
`reason`	`ViewShapeDeferralReason`	Why the shape is waiting: `collecting_samples` until enough evidence is available to author a mapping, `awaiting_script` until a transform covers it, `generation_failed` when script generation gave up, `catching_up` while its records backfill, `served` once resolved.
`schema_version`	`number \| null`	The schema version the shape belongs to. Null while no version is linked to it.
`created_at`	`ISODateString`

Shape Inspection Model

Field	Type
`view_id`	`string`
`deferral_id`	`string`
`episode`	`number`
`mapping_generation`	`number`
`version`	`number \| null`
`signatures`	`Record<string, string \| null>`
`decision`	`ViewMappingReuseDecision`
`candidates`	`{ transform_id: string; verdict: string; reason: string; exact_paths: string[]; present_null_paths: string[]; absent_paths: string[]; incompatible_paths: string[]; substitution_paths: string[]; unknown_paths: string[]; bindings: Record<...>; }[]`

Waiting Shape Hint Model

Field	Type	Description
`question`	`string`
`reason`	`string`
`paths`	`string[]`	Verified JSON bracket paths such as $["account"]["id"], with literal key characters escaped.
`requested_at`	`string`
`mapping_generation`	`number`
`view_id`	`string`
`deferral_id`	`string`
`episode`	`number`
`transform_id`	`string`

List Views

Endpoint

Retrieve a list of views for a project.

views:read

GET

/v1/projects/:project_id/views

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.

Query Parameters

Field	Type	Description
`order_by`	`string`	Field the results are sorted by. Defaults to `"created_at"`. Accepted values: `"created_at"`,`"name"`,`"updated_at"`.
`project_id`	`string`	Return only views in this project.
`collection_id`	`string`	Return only views reading from this collection.
`parent_view_id`	`string`	Return only views derived from this view.
`deleted_at`	`NullableDateFilter`	Filter on deletion state. Soft-deleted views are excluded unless you ask for them.
`limit`	`number`	Defaults to `25`. Minimum: `1`. Maximum: `200`.
`after`	`string`	Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page.
`before`	`string`	Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page.
`sort`	`string`	Defaults to `"asc"`. Accepted values: `"asc"`,`"desc"`.

Comments

after and before are mutually exclusive.

Response

200

{
  message: string;
  data: View[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve View

Endpoint

Retrieve a single view.

views:read

GET

/v1/projects/:project_id/views/:view_id

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Response

200

{
  message: string;
  data: View;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create View

Endpoint

Create a view that transforms records from a collection or another view.

views:write

POST

/v1/projects/:project_id/views

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.

Request Body

Field	Type	Requirement	Description
`name`	`string`	Required	Name for the view. Minimum length: `1`. Maximum length: `128`.
`output_schema`	`object[]`	Optional	The fields this view produces. Can be left until transforms define it.
`hint`	`string \| null`	Optional	Instructions the generator cannot infer from field names alone, such as a formatting rule or a business threshold.
`mapping_policy`	`object`	Optional
`project_id`	`string`	Optional	Project ID. Optional when using the /projects/:project/views route.
`collection_id`	`string`	Optional	Collection to derive from, when reading raw ingested records.
`parent_view_id`	`string`	Optional	View to derive from, when deriving from a view.
`transform_script`	`string`	Optional	TGL transform script. When set, the view skips automatic TGL generation. Minimum length: `1`. Maximum length: `65536`.
`transform_mode`	`string`	Optional	Whether a new schema version that no existing transform covers gets a script generated for it, or waits for you to write one. Defaults to auto. Accepted values: `"auto"`,`"manual"`.

Comments

A view reads from exactly one source: a collection, or another view to derive from.
The output schema defines the fields the view produces. A transform is created alongside the view to populate them.
Leaving the transform script empty queues it for generation instead of rejecting it, so a view can be created before its TGL is written.
Backfilling existing records starts shortly after creation and runs in the background. The view reports its progress while it catches up.
A view reads from exactly one place: set collection_id to derive from raw ingested records, or parent_view_id to derive from another view. Setting both, or neither, is rejected.
There is no source_id on this endpoint. One source can hold many collections, and the collection is what owns the schema and the records a view transforms. List a source's collections with GET /v1/projects/:project/collections?source_id=... and pass the one you want.
output_schema field names must be unique by name, cannot conflict on type, and cannot collide with a reserved query key such as limit or cursor.
transform_script cannot be whitespace-only. Supplying one activates the view's first transform immediately and skips automatic TGL generation.
Use hint for rules the generator cannot read off the field names: a formatting rule ("display_name should be Name (Type)"), a business threshold ("classify as high above 500"), or a disambiguation when a source field could map more than one way. Skip it for obvious mappings like renames and type conversions, which the generator already handles.

Response

201

{
  message: string;
  data: View;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Create Join View

Endpoint

Create a view that joins two existing views on a shared key.

views:write

POST

/v1/projects/:project_id/views/join

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.

Request Body

Field	Type	Requirement	Description
`name`	`string`	Required	Name shown for this join view. Minimum length: `1`. Maximum length: `128`.
`project_id`	`string`	Optional	Project the join view belongs to.
`base_view_id`	`string`	Required	View every output record starts from. Minimum length: `1`.
`joins`	`object[]`	Required	Views joined onto the base view, each with its own match fields.
`output_schema`	`object[]`	Optional	Fields the join produces. Leave empty to have one inferred. Defaults to `[]`.
`transform_script`	`string`	Optional	TGL transform script. Omit to have one generated. Minimum length: `1`. Maximum length: `65536`.
`hint`	`string`	Optional	Instructions the generator cannot infer from field names alone, such as a formatting rule or a business threshold. Maximum length: `4096`.

Comments

Both sides must be views in this project. Join a collection by creating a view over it first.
The join key must exist in the output schema of both sides.
A join view rebuilds when either side produces new records, so it trails its inputs rather than updating in the same instant.
Records are enriched with each joined view's latest value, by record timestamp, at the time they are processed. Records already produced are not revisited.
Each join clause's alias must be lowercase letters, digits and underscores, and start with a letter. It is how the clause's fields are addressed in the transform script.
transform_script cannot be whitespace-only. Omit it entirely to have one generated.
Use hint for rules the generator cannot read off the field names: a formatting rule ("display_name should be Name (Type)"), a business threshold ("classify as high above 500"), or a disambiguation when an input field could map more than one way. Skip it for obvious mappings like renames and type conversions, which the generator already handles.

Response

201

{
  message: string;
  data: View;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Update View

Endpoint

Update a view's name or output schema.

views:write

POST

/v1/projects/:project_id/views/:view_id

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Request Body

Field	Type	Requirement	Description
`mapping_policy`	`object`	Optional
`name`	`string`	Optional	Name for the view. Minimum length: `1`. Maximum length: `128`.
`output_schema`	`object[]`	Optional	The fields this view produces. Can be left until transforms define it.
`hint`	`string \| null`	Optional	Instructions the generator cannot infer from field names alone, such as a formatting rule or a business threshold.
`transform_mode`	`string`	Optional	Whether a new schema version that no existing transform covers gets a script generated for it, or waits for you to write one. Accepted values: `"auto"`,`"manual"`.
`view_transform_id`	`string`	Optional	Which transform adopts the schema versions still waiting for a script when switching transform_mode to manual. Required only when the view has more than one distinct transform script.
`deleted_at`	`null`	Optional	Send `null` to restore a view that is scheduled for deletion. The deletion date itself is set by the delete endpoint and cannot be written here.

Comments

Output schema changes are accepted only before a mapping or stored output exists. Changing an existing view's output schema requires a recovery transition that is not yet supported.
Mapping policy changes on an existing mapping require reviewed coverage recovery. Hint changes preserve accepted mappings and retry undecided work with the new hint.
What a view reads from is fixed at creation, so collection_id and parent_view_id are not accepted here. Create a new view to read from something else.
output_schema field names must be unique by name, cannot conflict on type, and cannot collide with a reserved query key such as limit or cursor.
Use hint for rules the generator cannot read off the field names: a formatting rule ("display_name should be Name (Type)"), a business threshold ("classify as high above 500"), or a disambiguation when a source field could map more than one way. Skip it for obvious mappings like renames and type conversions, which the generator already handles.

Response

200

{
  message: string;
  data: View;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete View

Endpoint

Delete a view and every view derived from it.

views:delete

DELETE

/v1/projects/:project_id/views/:view_id

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Comments

Views derived from this one are deleted with it.
The delete is refused while an active drain reads from this view or from any view that would cascade with it. Delete those drains first. Draft drains are removed silently.
Backfill and indexing work for the whole cascade is cancelled immediately, so a deleted view stops consuming capacity before its rows are removed.

Response

200

{
  message: string;
  data: View;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Force Delete View

Endpoint

Delete a view permanently, without waiting out its restore window.

views:delete

DELETE

/v1/projects/:project_id/views/:view_id/force

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Comments

Works on a live view as well as one already scheduled for deletion.
Views derived from this one go with it, and the rollups of any metric reading them are destroyed. The records they were built from are not affected, so both can be rebuilt.

Response

200

{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

List View Records

Endpoint

Retrieve the transformed records a view has produced.

views:read

GET

/v1/projects/:project_id/views/:view_id/records

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Comments

Records are only filterable on fields that have a facet. Filtering on any other field is rejected, so create a facet for a field before querying it.
Paging is forward-only. Pass pagination.next_cursor back as after to get the next page; a null next_cursor means there is nothing more to read. No prev_cursor is issued, and before is ignored.
A cursor is only valid for the query that produced it. Changing the sort direction, the filter, or (on a filtered read) the time range and reusing an older cursor returns a 400 rather than a page of skipped or repeated records, so start again without a cursor after any of those change.
start_at and end_at narrow a filtered read only. An unfiltered read returns the view's records regardless of the window, so pass a facet filter when you need a time-bounded result.
A cursor stays valid while Tailglow reorganizes stored data in the background, so a paging client is never interrupted by storage maintenance. It is a position in this result set, not a snapshot: records that arrive while you page appear only if they sort after your position.
after and before are mutually exclusive.

Response

200

{
  message: string;
  data: ViewRecord[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

List Waiting Shapes

Endpoint

Retrieve the event shapes a view has deferred because no transform serves them yet.

views:read

GET

/v1/projects/:project_id/views/:view_id/deferrals

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Query Parameters

Field	Type	Description
`resolved`	`string`	Filter by resolution. `false` returns only shapes still waiting. Accepted values: `"true"`,`"false"`.
`order_by`	`string`	Sort field. Defaults to `last_deferred_at`. Accepted values: `"first_deferred_at"`,`"last_deferred_at"`.
`limit`	`number`	Maximum number of items to return. Defaults to `25`. Minimum: `1`. Maximum: `200`.
`after`	`string`	Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page.
`before`	`string`	Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page.
`sort`	`string`	Sort direction for the result set. Defaults to `"desc"`. Accepted values: `"asc"`,`"desc"`.

Comments

Deferred records are stored, not lost. They backfill automatically once a script covers the shape, and each entry's reason says what unblocks it.
event_count is approximate: ingest retries can count an event more than once.
after and before are mutually exclusive.

Response

200

{
  message: string;
  data: ViewShapeDeferral[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Inspect Waiting Shape

Endpoint

Inspect structural differences and candidate output bindings for a waiting shape.

views:read

GET

/v1/projects/:project_id/views/:view_id/deferrals/:deferral_id

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`deferral_id`	`string`	Unique identifier of the deferral.

Response

200

{
  message: string;
  data: ViewShapeInspection;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Retrieve Waiting Shape Hint

Endpoint

Retrieve the model's current binding question for a waiting shape.

views:read

sources:read

GET

/v1/projects/:project_id/views/:view_id/deferrals/:deferral_id/hint

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`deferral_id`	`string`	Unique identifier of the deferral.

Comments

Requires both views:read and sources:read because model prose may refer to source records. Suggested paths are verified source fields in unambiguous JSON bracket notation.
Returns null when no current question remains. Answer using this question's episode, mapping_generation, requested_at, and transform_id.

Response 200 (1)

200

{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Response 200 (2)

200

{
  message: string;
  data: ViewPendingHint;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Decide Waiting Shape

Endpoint

Resolve the next action for one view and schema version.

views:write

POST

/v1/projects/:project_id/views/:view_id/deferrals/:deferral_id/decision

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`deferral_id`	`string`	Unique identifier of the deferral.

Request Body

Field	Type	Requirement	Description
`episode`	`integer`	Required	The deferral episode shown when the decision was inspected. Minimum: `1`.
`action`	`string`	Required	Authorize a bounded authoring attempt, answer a hint, or exclude this exact version in this view. Accepted values: `"author"`,`"hint"`,`"exclude"`.
`mapping_generation`	`integer`	Required	The mapping generation shown when the decision was inspected. Minimum: `1`.
`hint`	`string`	Optional	Answer to the model's binding question. Minimum length: `1`. Maximum length: `4096`.
`hint_requested_at`	`ISODateString`	Optional	Exact requested_at of the pending hint being answered.
`hint_transform_id`	`string`	Optional	Transform that owns the pending hint being answered. Minimum length: `1`. Maximum length: `32`.
`reason`	`string`	Optional	Required audit reason for an exclusion. Minimum length: `1`. Maximum length: `2000`.
`mapping_policy`	`object`	Optional	Explicit null, fallback, drop, and source-binding rules.

Comments

Authoring and hint answers reserve a bounded model budget. Exclusion covers unprocessed and future records of this exact version in this view.
Answering a hint requires hint; excluding a version requires reason. Exclusion covers unprocessed and future records with this exact schema version in this view.
Answering a pending model question also requires its exact hint_requested_at and hint_transform_id. Superseded or answered questions return a conflict; manual guidance without a pending question may omit both fields.

Response

200

{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

List View Transforms

Endpoint

Retrieve a list of a view's transforms.

views:read

GET

/v1/projects/:project_id/views/:view_id/transforms

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Query Parameters

Field	Type	Description
`order_by`	`string`	Field the results are sorted by. Creation order matches schema version order. Defaults to `"created_at"`. Accepted values: `"created_at"`,`"updated_at"`.
`status`	`ViewTransformStatus`	Return only transforms in this state.
`limit`	`number`	Defaults to `25`. Minimum: `1`. Maximum: `200`.
`after`	`string`	Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page.
`before`	`string`	Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page.
`sort`	`string`	Defaults to `"asc"`. Accepted values: `"asc"`,`"desc"`.

Comments

after and before are mutually exclusive.

Response

200

{
  message: string;
  data: ViewTransform[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve View Transform

Endpoint

Retrieve a single transform.

views:read

GET

/v1/projects/:project_id/views/:view_id/transforms/:transform_id

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`transform_id`	`string`	Unique identifier of the transform.

Response

200

{
  message: string;
  data: ViewTransform;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

List View Versions

Endpoint

Retrieve a list of the schema versions a view covers.

views:read

GET

/v1/projects/:project_id/views/:view_id/versions

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Query Parameters

Field	Type	Description
`order_by`	`string`	Field the results are sorted by. Defaults to `"version"`. Accepted values: `"version"`.
`status`	`ViewTransformStatus`	Return only versions whose transform is in this state.
`script_hash`	`string`	Return only versions served by this script. Take the value from a version's row. Minimum length: `64`. Maximum length: `64`.
`limit`	`number`	Maximum number of items to return. Defaults to `25`. Minimum: `1`. Maximum: `200`.
`after`	`string`	Cursor from `pagination.next_cursor` of a previous response. Returns the resources after that page.
`before`	`string`	Cursor from `pagination.prev_cursor` of a previous response. Returns the resources before that page.
`sort`	`string`	Sort direction for the result set. Defaults to `"desc"`. Accepted values: `"asc"`,`"desc"`.

Comments

One row per source schema version the view covers, newest version first. A view that reads another view has no schema versions, so its list is empty.
Versions sharing a script_hash run the same transform. Filter by it to see every version one script serves.
after and before are mutually exclusive.

Response

200

{
  message: string;
  data: ViewVersion[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve View Version

Endpoint

Retrieve one schema version a view covers.

views:read

GET

/v1/projects/:project_id/views/:view_id/versions/:version_id

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`version_id`	`string`	Unique identifier of the version.

Comments

version_id is the schema version NUMBER, the version a row carries, not a vta_ id.

Response

200

{
  message: string;
  data: ViewVersion;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create View Transform

Endpoint

Add a transform that maps incoming records into the view's output schema.

views:write

POST

/v1/projects/:project_id/views/:view_id/transforms

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Request Body

Field	Type	Requirement	Description
`collection_schema_version`	`integer \| null`	Optional	Collection schema version this transform covers. Null for view-to-view transforms.
`transform_script`	`string`	Optional	TGL transform script. Omit to have one generated. Minimum length: `1`. Maximum length: `65536`.

Comments

transform_script is TGL and must compile. A script that does not parse is rejected rather than stored, because an unparseable script would fail on every record it later touched.
The script must write every field the view's output schema declares.
Omitting the script queues the transform for generation instead of rejecting it.
A transform on a collection-backed view must name the collection_schema_version it covers. View-to-view transforms pass null, because they read another view's output rather than a collection schema.
transform_script cannot be whitespace-only. Omit it to have TGL generated instead.

Response

201

{
  message: string;
  data: ViewTransform;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Update View Transform

Endpoint

Update a transform's script.

views:write

POST

/v1/projects/:project_id/views/:view_id/transforms/:transform_id

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`transform_id`	`string`	Unique identifier of the transform.

Request Body

Field	Type	Requirement	Description
`transform_script`	`string`	Optional	TGL transform script. To clear and regenerate, use the regenerate endpoint instead. Minimum length: `1`. Maximum length: `65536`.
`conflict_resolution`	`string`	Optional	How conflicting schema versions are handled when a script edit fans out. Defaults to `"strand"`. Accepted values: `"strand"`,`"keep"`.
`dry_run`	`boolean`	Optional	Preview the edit: returns the per-version verdict report without changing anything. Defaults to `false`.
`preview_token`	`string`	Optional	The `edit_report.preview_token` from this edit's dry run. Required to save: it pins the save to the set of schema versions the preview reported on, so a version assigned or reassigned in between is rejected instead of silently included. Minimum length: `1`. Maximum length: `128`.

Comments

transform_script is TGL and must compile, and must write every field the view's output schema declares.
On collection-backed views, an edit fans out to every schema version using the same prior script and returns a verdict for each version. Additive reads report paths that produce null.
Conflicting versions are moved to queued placeholders by default. Set conflict_resolution to keep to leave those versions on their prior script.
Removing an output field is rejected while a metric, facet, child view, or join clause reads it. Consumer checks use the complete nested output path. Records already produced keep their existing values until the transform is re-backfilled.
Set dry_run to preview the per-version verdict report without saving. A dry run changes nothing and triggers nothing, and returns a preview_token alongside the report.
Saving requires the preview_token from that dry run. It pins the save to the set of schema versions the report described, so a version added or reassigned between the preview and the save cannot be silently included.
A save with a missing or outdated token is rejected with 409 and changes nothing. The error carries the report as it stands now, so the next preview is already in hand.
transform_script cannot be whitespace-only. To clear a script and have it regenerated, use the regenerate endpoint rather than sending an empty one.
Saving is a two-step gesture: send dry_run to get the report and its preview_token, then send the same edit with that token. A save without one, or with a token whose set has since changed, is rejected with 409 and a fresh report.

Response 200 (1)

200

{
  message: string;
  data: ViewTransform & { edit_report: { script_hash: string | null; version_verdicts: { collection_schema_version_id: string; version: number; verdict: "compatible" | "conflict"; action: "updated" | "kept" | "stranded"; null_paths: string[]; }[]; preview_token?: string | undefined; } };
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Additional Response Fields

Field	Type
`edit_report`	`{ script_hash: string \| null; version_verdicts: { collection_schema_version_id: string; version: number; verdict: "compatible" \| "conflict"; action: "updated" \| "kept" \| "stranded"; null_paths: string[]; }[]; preview_token?: string \| undefined; }`

Response 200 (2)

200

{
  message: string;
  data: ViewTransform & { edit_report: { script_hash: string | null; version_verdicts: never[]; } };
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Additional Response Fields

Field	Type
`edit_report`	`{ script_hash: string \| null; version_verdicts: never[]; }`

Generate View Transform Script

Endpoint

Queue TGL generation for a transform from the view's input and output schemas.

views:write

POST

/v1/projects/:project_id/views/:view_id/transforms/:transform_id/generate

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`transform_id`	`string`	Unique identifier of the transform.

Comments

Generation runs in the background. This returns once the work is queued, not once a script exists; poll the transform to see the result.
The generated script is written to the transform and replaces whatever was there.

Response

200

{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Re-backfill View Transform

Endpoint

Re-run a transform over every record the view has already read.

views:write

POST

/v1/projects/:project_id/views/:view_id/transforms/:transform_id/rebackfill

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`transform_id`	`string`	Unique identifier of the transform.

Comments

Use this after editing a script so existing records pick up the new logic. Without it, an edit only affects records that arrive afterwards.
The re-backfill runs in the background and replaces the view's output as it progresses. Anything reading the view sees a mix of old and new values until it finishes.
Metrics and views that depend on this one are rebuilt as well.

Response

200

{
  message: string;
  data: ViewTransform;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Regenerate View

Endpoint

Replace a view's output schema and queue every transform to be regenerated against it.

views:write

POST

/v1/projects/:project_id/views/:view_id/regenerate

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.

Request Body

Field	Type	Requirement	Description
`output_schema`	`object[]`	Optional	The fields the view should produce. Omit to regenerate against the current schema.
`hint`	`string \| null`	Optional	Instructions the generator cannot infer from field names alone, such as a formatting rule or a business threshold.

Comments

This is the schema-change path: it updates the output schema and re-queues the view's transforms in one step, so the scripts are rewritten to produce the new fields.
Existing records keep their old shape until the regenerated transforms backfill over them.
output_schema field names must be unique by name, cannot conflict on type, and cannot collide with a reserved query key such as limit or cursor.
Use hint for rules the generator cannot read off the field names: a formatting rule ("display_name should be Name (Type)"), a business threshold ("classify as high above 500"), or a disambiguation when a source field could map more than one way. Skip it for obvious mappings like renames and type conversions, which the generator already handles.

Response

200

{
  message: string;
  data: View;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete View Transform

Endpoint

Delete a transform from a view.

views:delete

DELETE

/v1/projects/:project_id/views/:view_id/transforms/:transform_id

Path Parameters

Field	Type	Description
`project_id`	`string`	Unique identifier of the project.
`view_id`	`string`	Unique identifier of the view.
`transform_id`	`string`	Unique identifier of the transform.

Comments

Records the transform already produced are left in place. Re-backfill the view's remaining transforms to rebuild its output without this one.

Response

200

{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Referenced Types

NullableDateFilter

Nullable date filters accept everything a date filter accepts, plus null to match records where the field is unset and not:null to match records where it is set.

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

ViewTransformMode

auto

manual

ViewStatus

empty

building

needs_transform

active

error

paused

cancelled

ViewJoinStatus

waiting_for_inputs

building_lookups

backfilling

active

error

ViewTransformStatus

queued

analyzing

active

error

draft

ViewTransformBackfillStatus

pending

enqueuing

in_progress

completed

failed

cancelled

ViewShapeDeferralReason

collecting_samples

needs_decision

needs_hint

manual_mapping

generating

budget_limited

shape_overflow

runtime_error

excluded

recovery_pending

awaiting_script

generation_failed

catching_up

served

What unblocks a waiting shape.