> ## Documentation Index > Fetch the complete documentation index at: https://docs.narrative.io/llms.txt > Use this file to discover all available pages before exploring further. # Schedule a job > Records which executor has claimed a `pending` job and moves it to `scheduled`. It is a no-op for a job in any other state. Idempotent. The response is the job as it stands after the call. `run` accepts a `scheduled` job, so an executor can claim a job here before it has the capacity to start it. Requires write access to jobs. ## OpenAPI ````yaml https://docs-cdn.narrative.io/api-reference/main/openapi.json post /jobs/{job_id}/schedule openapi: 3.1.1 info: contact: email: support@narrative.io name: Narrative Support url: https://www.narrative.io termsOfService: https://www.narrative.io/legal/terms-of-service x-logo: url: >- https://cdn.narrative.io/images/company-logos/prod/narrative-logo-text-white.svg backgroundColor: rgb(9, 34, 166) altText: Narrative Logo description: >- The [Narrative Data Collaboration Platform](https://app.narrative.io) API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The current version is a pre-release beta. It may result in unexpected behavior and there may be breaking changes in future releases up to the 1.0 release. title: Narrative Data Collaboration Platform API version: 2.4.x servers: - url: https://api-dev.narrative.io - url: https://api.narrative.io security: [] tags: - name: Access Rules description: >- Access rules let data providers control who can purchase their data and the terms of purchase. The `access-rules` API allows you to manage access rules for your datasets. Related guides: - [What is an access rule?](https://kb.narrative.io/access-rules) - name: Agent Conversations description: >- Build LLM-driven workflows that can call MCP tools, ask the caller for input, and return structured answers. A conversation pins a model, a system prompt, and a tool catalog. Each run sends the model a user message (or a batch of tool outputs from a previously-paused run); the model decides whether to answer directly, call a server-side tool (resolved by the platform via Model Context Protocol), or call a client-side tool (which pauses the run with `requires_action` and waits for the caller to reply). Related guides: - [Agent Conversations Reference](https://docs.narrative.io/reference/architecture/agent-conversations) - [Error catalog](https://docs.narrative.io/reference/architecture/agent-conversations/errors/conversation-not-found) - name: MCP Connections description: >- Connect external (non-Narrative) MCP servers so agent runs can call their tools with the calling user's own OAuth authorization. A connection is created interactively: `POST /mcp-connections` runs OAuth discovery and Dynamic Client Registration against the server and returns a consent URL; the user authorizes in a browser; the authorization server redirects to `GET /mcp-connections/callback`, which stores the authorization code and sends the browser on to the Narrative app; the app calls `POST /mcp-connections/complete` with the user's own bearer token, which exchanges the code and marks the connection `connected`. That last step is authenticated on purpose. The callback is public — it's a cross-site browser redirect, so no bearer reaches it — so it is not allowed to complete anything. Only the user who started the flow can turn the stored code into a token. Tokens are stored encrypted and used server-side — they are never returned by the API. Once connected, reference the connection by id from an agent run's `mcp_servers[].connection_id`. - name: App Invites description: >- App invites allow applications to create one-time, shareable links on behalf of their users. These links enable users to invite third parties who do not have a Narrative account to perform actions within the application. For example, a Narrative user can send an invite link to a third party who then completes a Pinterest OAuth flow and creates a connector profile in the inviter's account, allowing the inviter to deliver audience data to the third party's Pinterest account without the third party needing a Narrative account. This API is intended to be used by applications (via app client credentials) to create and manage invites on behalf of their users, which can then be shared with invitees. - name: Apps description: >- Apps are applications bundled with a UI that can perform various actions on behalf of a user utilizing the Narrative API. Related guides: - [Building a Narrative Native App](https://www.narrative.io/knowledge-base/how-to-guides/building-a-narrative-native-app) - name: Access Tokens description: >- System Access Tokens are long-lived bearer credentials for calling the API without a user present. A token belongs to a company, carries an explicit list of permissions, and expires on a date you choose — at least a day out and at most a year. `admin` access cannot be granted to one. `POST /access-tokens/tokens` is the only endpoint that returns the credential. Everything after that works in terms of the token's id: the list, get and update responses describe a token without ever repeating its `access_token`. If you lose it, delete the token and create another. Related guides: - [How to Create an API Token](https://www.narrative.io/knowledge-base/how-to-guides/understanding-narratives-apis/create-an-api-token) - name: Attributes description: >- An attribute models a standardized data point available for sale on the Narrative marketplace. Narrative automatically turns data points from provider datasets into attributes so that buyers can purchase well-formed, standardized data from any supplier on the marketplace. - name: Auth description: >- API token is a crucial step for developers to securely authenticate requests to the Narrative API Related guides: - [How to Create an API Token](https://www.narrative.io/knowledge-base/how-to-guides/understanding-narratives-apis/create-an-api-token) - name: Authentication description: User login and registration - name: Billings description: Used by Narrative internally to bill customers - name: Companies description: A collection of employees - name: Company Marketing Information description: Useful information related to companies - name: Compute Pools description: >- Compute pools represent compute resources (e.g. Snowflake warehouses) provisioned within a data plane. Companies can manage and share compute pools, assign them to jobs, and set a default compute pool on data planes. - name: Connections description: Associations between connectors and datasets - name: Data Shops description: |- Self-hosted website to sell your data Related guides: - [Setting up your datashop](https://www.narrative.io/knowledge-base/how-to-guides/shop-builder/settting-up-your-data-shop) - name: Data Streams description: >- The `data-stream` API endpoints allows one to create and update data-streams. Additionally the endpoints allow finding data-streams using free text search. A few of the endpoints are behind authorization. Update endpoint allows a client to post an edited data-stream document as is, without having to change its shape. The API ensures that only certain fields are allowed to be modified. Attempts to modify fields not up for client modifications are ignored. Related guides: - [What is a data stream?](https://kb.narrative.io/what-is-a-data-stream) - name: Contracts description: Contracts related APIs - name: Datasets description: >- Any kind of data, in any schema, can be pushed into the Narrative Data Collaboration Platform as a dataset exactly as it is stored in your own system. The `datasets` API allows you to manage your datasets. - name: Derivations description: >- Derivation rules describe how the value of one Rosetta Stone attribute can be computed from another — for example, hashing a raw email into a SHA-256 hashed email. Each rule carries a transformation expression that reads the source attribute's value through `$source`. The `derivations` API allows you to browse the rules your company can use — the ones it owns plus the ones shared with it through collaborators. Creating and changing them requires an `admin` grant on `attribute_derivations`, and a rule can only be changed by the company that owns it. - name: Destinations description: >- Destinations associate a subscription to a profile. Optionally, ad-hoc quick settings can be configured to a destination. Those quick settings have to match the format defined on the app manifest. - name: Installations description: Installations of Applications for a profile - name: Jobs description: >- Jobs represent an operation done on a given data plane. All jobs today are tied to a query that represents a forecast or a materialized view. The jobs API provides an interface for interacting with the jobs table, which stores various operations involving reading or writing data. This API allows users to retrieve detailed information about specific jobs, including NQL forecasts and materialized views. - name: Mappings description: >- A mapping is a transformation from a dataset to an attribute. Defining a mapping between a dataset and an attribute makes the dataset eligible to participate in subscriptions where a buyer is purchasing the target attribute. - name: Model Inference description: Model Inference - name: Model Training description: >- Train machine learning models on datasets, e.g. text classifiers used to power attribute mappings. - name: Models description: >- Machine learning models for training and inference. Models can be stored in HuggingFace or Narrative repositories and have configurable collaborator permissions for training and inference access. The `models` API allows you to list, retrieve, and update models accessible to your company. - name: NQL description: >- Narrative Query Language (NQL) is a specialized, SQL-inspired language designed to query and manipulate data within the Narrative platform. While it looks and feels much like standard SQL, it offers extended functionality and syntax that let you leverage platform-specific features—such as referencing datasets by their IDs, creating materialized views, or generating forecasts—without having to manage the complexities of different query engines behind the scenes. NQL queries can ultimately compile down to multiple underlying engines (e.g., Snowflake, Spark) to execute your requests efficiently in the Narrative ecosystem. - name: Payment Methods description: Payment methods used to purchase data - name: Products description: Internal routes used to offer datastream as products - name: Profiles description: >- App profiles are associated with an installation. They represent a reference to a configuration that the app can use to save confidential information outside of Narrative's control. Profiles are currently used to configure settings for connector apps. - name: Resources description: >- Narrative gives you access to managed resources, like your own AWS S3 bucket, so that you can effortlessly buy and sell data on the platform. The `resources` API allows you to manage your resources. - name: Schema Inference description: >- The `schema-inference` API analyzes submitted files to automatically infer and return their structure as a dataset schema. - name: Schema Presets description: >- The `schema-presets` API allows you to list the available schema presets, get detailed information about a specific one and manage its life cycle. You can create a schema preset from scratch or create one based on an existing one, administrators can create platform wide available (public) schema preset. - name: Subscriptions description: >- In the Narrative Data Collaboration Platform a subscription represents a set of rules dictating the commercial terms related to the licensing of data. The `subscriptions` API allows you to set and get information about `subscription` objects owned by the authenticated account. - name: Uploads description: >- The `uploads` API allows you to send files to Narrative and use them to perform tasks like creating a list or adding data to a dataset. - name: Usage description: >- The `usage` API enables the recording of usage events associated with a product. - name: Webhooks description: >- Webhooks push events to a URL you control instead of making you poll for them. You create a subscription with the endpoint you want events sent to and a filter describing which events you want. Two kinds of subscription exist: job subscriptions follow the lifecycle of Narrative jobs, and app subscriptions follow the events a Narrative app reports through `POST /apps/events`. Creating a subscription returns a `secret`. Narrative sends it back in the `X-Narrative-Secret` header on every delivery, and comparing the two is how you tell a real callback from a forged one — so store it and do not share it. Deliveries are described under the "Event delivery" webhook below. Return any 2xx; anything else is retried with exponential backoff, and because a retry reuses the envelope's `id`, handlers should be idempotent on it. - name: Workflows description: >- The `workflows` API allows you to create, schedule, trigger, and archive workflows. Workflows are defined using a serverlessworkflow YAML specification. paths: /jobs/{job_id}/schedule: post: tags: - Jobs summary: Schedule a job description: >- Records which executor has claimed a `pending` job and moves it to `scheduled`. It is a no-op for a job in any other state. Idempotent. The response is the job as it stands after the call. `run` accepts a `scheduled` job, so an executor can claim a job here before it has the capacity to start it. Requires write access to jobs. parameters: - $ref: '#/components/parameters/JobId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScheduleJobRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JobResponse' '400': description: This error is raised when the request body is malformed. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Returned with an empty body when the job cannot be found. security: - BearerAuth: [] components: parameters: JobId: in: path name: job_id required: true description: Unique identifier for a job. schema: type: string format: uuid schemas: ScheduleJobRequest: type: object required: - executor description: >- Records which executor has claimed a `pending` job and moves it to `scheduled`. properties: executor: $ref: '#/components/schemas/ExecutorId' example: executor: job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266 JobResponse: description: >- A job. Every job carries the same envelope of fields — see `JobBase` — but `input` and `result` hold job-type-specific payloads, so the response is a union over `type`: pick the branch whose `type` matches and you get the typed `input` and `result` for that kind of job. The union is open on purpose. Job types are free strings on the server, so a type this spec version does not describe lands in `OtherJobResponse`, where both fields stay free-form. No branch closes itself to extra properties, and new job types can appear without a spec change. `input` and `result` are returned exactly as they were stored when the job was enqueued or completed. The server never reshapes them, so a field a job type gained after a row was written is absent from that row rather than null. The typed branches describe what the current code writes; fields that have not always been written are left out of each branch's `required` list. `result` is `null` in every branch until the job reaches a terminal state. oneOf: - $ref: '#/components/schemas/MaterializeViewJobResponse' - $ref: '#/components/schemas/NqlForecastJobResponse' - $ref: '#/components/schemas/DatasetsSampleJobResponse' - $ref: '#/components/schemas/DatasetsCalculateColumnStatsJobResponse' - $ref: '#/components/schemas/CollectAccessRulesBillingDataJobResponse' - $ref: '#/components/schemas/DatasetsDeliverDataJobResponse' - $ref: '#/components/schemas/ModelInferenceRunJobResponse' - $ref: '#/components/schemas/DatasetsDeleteTableJobResponse' - $ref: '#/components/schemas/DatasetsExecuteDmlJobResponse' - $ref: '#/components/schemas/DatasetsCreateTableJobResponse' - $ref: '#/components/schemas/DatasetsTruncateTableJobResponse' - $ref: >- #/components/schemas/DatasetsEnforceTableTtlRetentionPolicyJobResponse - $ref: '#/components/schemas/DatasetsEnforceRowTtlRetentionPolicyJobResponse' - $ref: '#/components/schemas/DatasetsCalculateAffectedRowsJobResponse' - $ref: '#/components/schemas/ModelTrainingRunJobResponse' - $ref: '#/components/schemas/ModelsDeliverModelJobResponse' - $ref: '#/components/schemas/ModelsTrainClassifierJobResponse' - $ref: '#/components/schemas/HealthCheckJobResponse' - $ref: '#/components/schemas/OtherJobResponse' Error: type: object required: - error - error_description properties: error: type: string example: Unauthorized error_description: type: string example: You are not authorized to use this endpoint. ExecutorId: description: Identifier of a job executor. Non-blank, at most 255 characters. type: string minLength: 1 maxLength: 255 example: job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266 MaterializeViewJobResponse: description: >- Refreshes a materialized view: runs the view's compiled SELECT and writes the rows into the target dataset. Runs the `materialized-view-refresh` operator. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - materialize-view input: $ref: '#/components/schemas/MaterializeViewJobInput' result: oneOf: - $ref: '#/components/schemas/MaterializeViewJobResult' - type: 'null' example: job_id: 2a5b9ad7-dc8f-47bb-8e62-843a38f8054c company_id: 1 data_plane_id: f79cbdae-4848-47ca-95e8-69588364d185 compute_pool_id: null request_source: type: api_user company_id: 1 user_id: 407 state: completed type: materialize-view operator_type: materialized-view-refresh tags: [] input: nql: >- CREATE MATERIALIZED VIEW "test_stats" AS SELECT "value" FROM "company_data"."10674" compiled_select: |- SELECT `ds_10674`.`value` FROM narrative.datasets.ds_10674 `ds_10674` create_as_view: null dataset_id: 10736 billing_enabled: null stats_enabled: true contains_delta_syntax: null first_run: false merge: true partitions: null snowflake_create_table: null snowflake_insert_statement: null chunk_metadata: null nio_last_modified_at: null delta_dataset_bounds: null write_mode: append executor: job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266 execution_cluster: shared idempotency_key: >- 10736:29329c64e7b8a4eda86aaabe04872b832ab456b5543d0c259c812525391f158c:669a5f8e4f373c2f907700decde47511aac6470f5698e2b856fb07f09160e5f2 result: dataset_id: 10736 snapshot_id: 1724919539450264600 recalculation_id: abf9a2ec-426b-4751-bd16-fcb435061925 row_stats: null dequeued_at: '2023-10-31T11:19:13.400498Z' created_at: '2023-10-31T11:19:13.400498Z' updated_at: '2023-10-31T11:25:08.327209Z' attempted_at: '2023-10-31T11:19:13.400498Z' attempt_version: 1 ended_at: '2023-10-31T11:25:08.327194Z' workflow_id: null workflow_run_id: null NqlForecastJobResponse: description: >- Estimates how many rows a query would return and what they would cost, without buying them. Enqueued by `EXPLAIN`-style NQL. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - nql-forecast input: $ref: '#/components/schemas/NqlForecastJobInput' result: oneOf: - $ref: '#/components/schemas/NqlForecastJobResult' - type: 'null' DatasetsSampleJobResponse: description: >- Reads a sample of rows from a dataset. Runs the `datasets_execute_select` operator, except on the Narrative data plane without a compute pool, where the operator type stays `datasets_sample`. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_sample input: $ref: '#/components/schemas/DatasetsSampleJobInput' result: oneOf: - $ref: '#/components/schemas/DatasetsSampleJobResult' - type: 'null' DatasetsCalculateColumnStatsJobResponse: description: >- Computes per-column statistics for a dataset. Two input shapes are in flight. V1 names the columns to collect and which statistics to collect for each; V2 hands the operator a SELECT the API already compiled. Which one a job carries depends on the path that enqueued it, so `input` accepts either. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_calculate_column_stats input: $ref: '#/components/schemas/DatasetsCalculateColumnStatsJobInput' result: oneOf: - $ref: '#/components/schemas/DatasetsCalculateColumnStatsJobResult' - type: 'null' CollectAccessRulesBillingDataJobResponse: description: >- Counts, per access rule, how many rows a materialized-view refresh pulled and what they cost, so the refresh can be billed. Enqueued after the refresh it reports on, and points back at it through `input.refresh_job_id`. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - materialized_views_collect_access_rules_billing_data input: $ref: '#/components/schemas/CollectAccessRulesBillingDataJobInput' result: oneOf: - $ref: '#/components/schemas/CollectAccessRulesBillingDataJobResult' - type: 'null' DatasetsDeliverDataJobResponse: description: >- Delivers a dataset snapshot out to a connected app. One job per connection, so a dataset delivered to several destinations produces several of these. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_deliver_data input: $ref: '#/components/schemas/DatasetsDeliverDataJobInput' result: oneOf: - $ref: '#/components/schemas/DatasetsDeliverDataJobResult' - type: 'null' ModelInferenceRunJobResponse: description: >- Runs one inference call against a model on the data plane. The conversation, the model binding, and the sampling settings all travel in `input`; the model's answer comes back in `result`. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - model_inference_run input: $ref: '#/components/schemas/ModelInferenceRunJobInput' result: oneOf: - $ref: '#/components/schemas/ModelInferenceRunJobResult' - type: 'null' DatasetsDeleteTableJobResponse: description: Drops a dataset's underlying table. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_delete_table input: $ref: '#/components/schemas/DatasetsDeleteTableJobInput' result: oneOf: - $ref: '#/components/schemas/DatasetsDeleteTableJobResult' - type: 'null' DatasetsExecuteDmlJobResponse: description: Runs a DML statement — an NQL `DELETE` or `UPDATE` — against a dataset. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_execute_dml input: $ref: '#/components/schemas/DatasetsExecuteDmlJobInput' result: oneOf: - $ref: '#/components/schemas/DatasetsExecuteDmlJobResult' - type: 'null' DatasetsCreateTableJobResponse: description: Creates a dataset's underlying table. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_create_table input: $ref: '#/components/schemas/DatasetsCreateTableJobInput' result: oneOf: - $ref: '#/components/schemas/DatasetsCreateTableJobResult' - type: 'null' DatasetsTruncateTableJobResponse: description: Empties a dataset's underlying table, leaving the table itself in place. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_truncate_table input: $ref: '#/components/schemas/DatasetsTruncateTableJobInput' result: oneOf: - $ref: '#/components/schemas/DatasetsTruncateTableJobResult' - type: 'null' DatasetsEnforceTableTtlRetentionPolicyJobResponse: description: >- Applies a dataset's table-level TTL retention policy — drops the table once it has outlived the policy. Runs the `datasets_enforce_table_ttl_retention_policy` operator. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_enforce_table_ttl_retention_policy input: $ref: '#/components/schemas/DatasetsEnforceTableTtlRetentionPolicyJobInput' result: oneOf: - $ref: >- #/components/schemas/DatasetsEnforceTableTtlRetentionPolicyJobResult - type: 'null' DatasetsEnforceRowTtlRetentionPolicyJobResponse: description: >- Applies a dataset's row-level TTL retention policy — deletes rows that have outlived it. Runs the `datasets_enforce_row_ttl_retention_policy` operator. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_enforce_row_ttl_retention_policy input: $ref: '#/components/schemas/DatasetsEnforceRowTtlRetentionPolicyJobInput' result: oneOf: - $ref: >- #/components/schemas/DatasetsEnforceRowTtlRetentionPolicyJobResult - type: 'null' DatasetsCalculateAffectedRowsJobResponse: description: >- Counts how many rows a pending statement would touch. Runs the `datasets_execute_select` operator and the row it returns is read as the count, which is why the result carries that operator's type rather than this job's. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - datasets_calculate_affected_rows input: $ref: '#/components/schemas/DatasetsCalculateAffectedRowsJobInput' result: oneOf: - $ref: '#/components/schemas/DatasetsCalculateAffectedRowsJobResult' - type: 'null' ModelTrainingRunJobResponse: description: >- Fine-tunes a base model on a dataset and publishes the result to a model repository. `result` is whatever the training operator posted when it completed the job — the API stores it as sent rather than reshaping it, so it is free-form here. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - model_training_run input: $ref: '#/components/schemas/ModelTrainingRunJobInput' result: $ref: '#/components/schemas/JobResult' ModelsDeliverModelJobResponse: description: >- Delivers a trained model out to a connected app. Enqueued once training finishes, one job per connection. `result` is whatever the delivery operator posted when it completed the job — the API stores it as sent rather than reshaping it, so it is free-form here. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - models_deliver_model input: $ref: '#/components/schemas/ModelsDeliverModelJobInput' result: $ref: '#/components/schemas/JobResult' ModelsTrainClassifierJobResponse: description: >- Trains a classifier. Both `input` and `result` are free-form. The input is the training config exactly as the caller submitted it, and the result is whatever the operator posted on completion — neither passes through a typed class in the marketplace, so there is no fixed shape to document. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - models_train_classifier input: $ref: '#/components/schemas/JobInput' result: $ref: '#/components/schemas/JobResult' HealthCheckJobResponse: description: |- Checks that a data plane is reachable and can run work. Enqueued by `POST /data-planes/{data_plane_id}/health-check`. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: type: string enum: - health_check input: $ref: '#/components/schemas/HealthCheckJobInput' result: $ref: '#/components/schemas/JobResult' OtherJobResponse: description: >- A job of a type this spec version does not describe. `input` and `result` stay free-form here. This branch is what keeps `JobResponse` open. Job types are free strings on the server, and `input` and `result` are stored as arbitrary JSON, so a client will meet job types added after it was generated, and rows written before the current shapes existed. Both land here rather than failing to parse. Read `type` to find out what you actually have. allOf: - $ref: '#/components/schemas/JobBase' type: object required: - type - input - result properties: type: description: >- Any job type other than the ones `JobResponse` describes a branch for. type: string not: enum: - materialize-view - nql-forecast - datasets_sample - datasets_calculate_column_stats - materialized_views_collect_access_rules_billing_data - datasets_deliver_data - model_inference_run - datasets_delete_table - datasets_execute_dml - datasets_create_table - datasets_truncate_table - datasets_enforce_table_ttl_retention_policy - datasets_enforce_row_ttl_retention_policy - datasets_calculate_affected_rows - model_training_run - models_deliver_model - models_train_classifier - health_check input: $ref: '#/components/schemas/JobInput' result: $ref: '#/components/schemas/JobResult' JobBase: description: >- The fields every job carries, whatever its type. Each branch of `JobResponse` adds `type`, `input`, and `result` on top of these. Every key listed here is present on every job. The ones typed as nullable are sent as `null` rather than omitted when they have no value. type: object required: - job_id - company_id - request_source - state - operator_type - tags - execution_cluster - idempotency_key - created_at - updated_at - attempted_at - attempt_version properties: job_id: $ref: '#/components/schemas/JobId' company_id: description: The company the job belongs to. type: integer format: int64 data_plane_id: description: >- The data plane the job runs on. Jobs enqueued without one are reported as running on the Narrative data plane, `f79cbdae-4848-47ca-95e8-69588364d185`, so this is never null in practice. type: - string - 'null' format: uuid compute_pool_id: description: The compute pool associated with the job, if any. type: - string - 'null' format: uuid request_source: $ref: '#/components/schemas/RequestSource' state: $ref: '#/components/schemas/State' operator_type: description: >- Which operator runs the job, e.g. `materialized-view-refresh` or `datasets_execute_select`. Finer-grained than `type`: several job types can share one operator, and where no such mapping exists the two are equal. type: string tags: description: Free-form labels attached to the job. type: array items: type: string minLength: 1 maxLength: 255 executor: description: >- The internal job executor tied to the job. Null until an executor picks the job up. type: - string - 'null' execution_cluster: $ref: '#/components/schemas/ExecutionClusterType' idempotency_key: description: The unique key the job was enqueued under. type: string minLength: 1 maxLength: 255 dequeued_at: description: When the job was taken off the queue. Null while it is still queued. type: - string - 'null' format: date-time created_at: description: The timestamp representing when the job was created. type: string format: date-time updated_at: description: The timestamp representing when the job was updated. type: string format: date-time attempted_at: description: >- When the job's current attempt started. A job can be retried; each retry is a new attempt, so this advances to the latest one, while `created_at` stays at the original submission. type: string format: date-time attempt_version: description: >- Which attempt this is: 1 for the first, increasing by one on each retry. type: integer ended_at: description: >- The timestamp representing when the job finished. Null until the job reaches a terminal state. type: - string - 'null' format: date-time workflow_id: description: >- The id of the workflow that enqueued the job. Null for jobs not enqueued by a workflow. type: - string - 'null' format: uuid workflow_run_id: description: >- The id of the workflow run that enqueued the job. Null for jobs not enqueued by a workflow run. type: - string - 'null' format: uuid MaterializeViewJobInput: description: >- Jobs enqueued today carry every field below, with `null` where a value is unset. Most of the optional fields were added over the life of this job type, so a row written before a field existed lacks that key. type: object required: - nql - compiled_select - dataset_id properties: nql: description: The `CREATE MATERIALIZED VIEW` statement the view was defined with. type: string compiled_select: description: The SELECT that `nql` compiles to. This is what the operator runs. type: string create_as_view: description: >- Write a view instead of a table. Null when the job was enqueued without the option. type: - boolean - 'null' dataset_id: description: The dataset the refreshed rows are written to. type: integer format: int64 billing_enabled: description: Whether the refresh bills for the rows it reads. type: - boolean - 'null' stats_enabled: description: >- Whether extended dataset statistics are on for the view. Only the V1 stats path reads this. type: - boolean - 'null' contains_delta_syntax: description: Whether `nql` uses DELTA syntax. type: - boolean - 'null' first_run: description: Whether this is the view's first refresh. type: - boolean - 'null' merge: description: Whether the refresh merges into the target rather than replacing it. type: - boolean - 'null' partitions: description: >- Partition configuration for the write. Null when the view is unpartitioned; never an empty array. type: - array - 'null' minItems: 1 items: $ref: '#/components/schemas/MaterializeViewJobPartition' snowflake_create_table: description: >- Snowflake `CREATE TABLE` used to support MERGE. Null outside the Snowflake data plane. type: - string - 'null' snowflake_insert_statement: description: >- Snowflake INSERT used to support MERGE. Null outside the Snowflake data plane. type: - string - 'null' chunk_metadata: description: >- Chunking state when the refresh is split across several jobs. Null when it is not. oneOf: - $ref: '#/components/schemas/MaterializeViewJobChunkMetadata' - type: 'null' nio_last_modified_at: description: The `_nio_last_modified_at` watermark the refresh writes. type: - string - 'null' format: date-time delta_dataset_bounds: description: >- Bounds for the DELTA sources the refresh reads. Null on jobs enqueued without them, which does not mean the query has no DELTA. type: - array - 'null' items: $ref: '#/components/schemas/MaterializeViewJobDeltaDatasetBound' write_mode: description: >- Whether the refresh appends to the target dataset or overwrites it. Null when unset. type: - string - 'null' enum: - append - overwrite - null example: nql: >- CREATE MATERIALIZED VIEW "test_stats" AS SELECT "value" FROM "company_data"."10674" compiled_select: |- SELECT `ds_10674`.`value` FROM narrative.datasets.ds_10674 `ds_10674` create_as_view: null dataset_id: 10736 billing_enabled: null stats_enabled: true contains_delta_syntax: null first_run: false merge: true partitions: null snowflake_create_table: null snowflake_insert_statement: null chunk_metadata: null nio_last_modified_at: null delta_dataset_bounds: null write_mode: append MaterializeViewJobResult: description: >- Written by the completion handler and by the Spark executor alike. `recalculation_id` and `row_stats` were added after this job type existed, so older completed rows lack them. type: object required: - dataset_id - snapshot_id properties: dataset_id: description: The dataset the rows were written to. type: integer format: int64 snapshot_id: description: >- The Iceberg snapshot the write produced. The Snowflake data plane passes a numeric snapshot id here too, so this is always a number; `0` when the value it sent did not parse as one. type: integer format: int64 recalculation_id: description: >- The statistics recalculation this refresh triggered. Only the V1 stats path sets it. type: - string - 'null' format: uuid row_stats: description: >- Row counts for the write. Null when the operator did not report them. oneOf: - $ref: '#/components/schemas/MaterializeViewJobRowStats' - type: 'null' example: dataset_id: 10736 snapshot_id: 1724919539450264600 recalculation_id: abf9a2ec-426b-4751-bd16-fcb435061925 row_stats: null NqlForecastJobInput: type: object required: - nql - compiled_sql properties: nql: description: The NQL that was forecast. type: string compiled_sql: description: The SQL that `nql` compiles to. This is what the operator runs. type: string example: nql: >- EXPLAIN SELECT narrative.rosetta_stone."age" FROM narrative.rosetta_stone WHERE narrative.rosetta_stone."age" > 50 compiled_sql: |- SELECT `t`.`age` FROM narrative.datasets.ds_63 `t` WHERE `t`.`age` > 50 NqlForecastJobResult: description: >- The forecast, or the reason it could not be produced. Exactly one of `success` / `failure` is present — this is a Scala sum type encoded by constructor name, so the absent branch is not sent as null. Note the capitalised `Forecast` key inside `success.result`: that inner type is encoded with a different Circe configuration than the fields around it, which leaves the constructor name as written. oneOf: - $ref: '#/components/schemas/NqlForecastJobSuccess' - $ref: '#/components/schemas/NqlForecastJobFailure' DatasetsSampleJobInput: type: object required: - dataset_id - compiled_sql properties: dataset_id: description: The dataset being sampled. type: integer format: int64 compiled_sql: description: >- The SELECT that produces the sample. Compiled by the API, run by the operator. type: string example: dataset_id: 10736 compiled_sql: >- SELECT `ds_10674`.`value` FROM narrative.datasets.ds_10674 `ds_10674` LIMIT 100 DatasetsSampleJobResult: description: >- How many rows the sample holds. The rows themselves are stored separately, not returned here. Two shapes are stored. A job completed with the rows it selected (`datasets_execute_select`), or by the legacy executor, carries `type` and `row_count`. A job completed with the bare `datasets_sample` marker stores an empty object, so neither key is guaranteed. type: object properties: type: description: Repeated inside the result by the encoder that writes it. type: string enum: - datasets_sample row_count: type: integer format: int64 examples: - type: datasets_sample row_count: 100 - {} DatasetsCalculateColumnStatsJobInput: description: >- Either input shape. A payload tells you which one it is: V2 carries `compiled_sql`, V1 does not. `anyOf` rather than `oneOf` because a V2 payload also satisfies V1's one required key, and a stored row carrying both — nothing writes one today, but nothing stops one either — should still validate. anyOf: - $ref: '#/components/schemas/DatasetsCalculateColumnStatsJobInputV2' - $ref: '#/components/schemas/DatasetsCalculateColumnStatsJobInputV1' DatasetsCalculateColumnStatsJobResult: description: >- A marker that the job finished. The statistics themselves are written to the dataset, not returned here. A job completed through the API carries only `type`; one completed by the legacy executor also carries `total_rows` and `column_count`. type: object required: - type properties: type: type: string enum: - datasets_calculate_column_stats total_rows: description: How many rows the dataset had when the statistics were computed. type: integer format: int64 column_count: description: How many columns statistics were computed for. type: integer examples: - type: datasets_calculate_column_stats - type: datasets_calculate_column_stats total_rows: 12000 column_count: 4 CollectAccessRulesBillingDataJobInput: type: object required: - nio_last_modified_at - compiled_query - refresh_job_id properties: dataset_id: description: The dataset the refresh wrote to. Null on jobs enqueued without one. type: - integer - 'null' format: int64 nio_last_modified_at: description: >- The job counts rows whose `_nio_last_modified_at` matches this watermark. type: string format: date-time compiled_query: description: >- The query that counts the rows, compiled by the API so the operator needs no query logic. type: string refresh_job_id: description: The `materialize-view` job whose rows this job bills for. type: string format: uuid example: dataset_id: 10736 nio_last_modified_at: '2024-01-28T00:00:00Z' compiled_query: SELECT `t`.`_nio_access_rule_id` FROM narrative.datasets.ds_10736 `t` refresh_job_id: 2a5b9ad7-dc8f-47bb-8e62-843a38f8054c CollectAccessRulesBillingDataJobResult: description: >- One entry per access rule the refresh read from. A job completed through the API carries `type` as well; one completed by the Spark executor does not. type: object required: - sources properties: type: description: Repeated inside the result by the completion handler. type: string enum: - materialized_views_collect_access_rules_billing_data sources: type: array items: $ref: '#/components/schemas/CollectAccessRulesBillingDataSource' example: type: materialized_views_collect_access_rules_billing_data sources: - access_rule_id: 88 rows: 1200 price_per_row: currency: USD microcents: 250 DatasetsDeliverDataJobInput: type: object required: - dataset_id - external_id properties: app_id: description: >- The app being delivered to. Null on deliveries not routed through an app installation. type: - integer - 'null' format: int64 connection_id: description: The connection being delivered to. type: - string - 'null' format: uuid dataset_id: description: The dataset being delivered. type: integer format: int64 external_id: description: The dataset's external identifier, as the destination knows it. type: string snapshot_id: description: >- The snapshot being delivered. A string, not a number — the Snowflake data plane passes a numeric snapshot id through this field as text. type: - string - 'null' maintenance_window_predicate: description: >- SQL restricting the delivery to a maintenance window. Null when the delivery covers the whole snapshot. type: - string - 'null' example: app_id: 142 connection_id: 0f1e2d3c-4b5a-4968-9788-6a5b4c3d2e1f dataset_id: 10736 external_id: nio_10736 snapshot_id: '1724919539450264600' maintenance_window_predicate: null DatasetsDeliverDataJobResult: description: >- Empty. The API records nothing beyond the job reaching `completed` — what was delivered is already in the input, and the destination's own response is not kept. type: object example: {} ModelInferenceRunJobInput: description: >- Jobs enqueued today carry every field below. `tools` and `tool_choice` were added after this job type existed, so older rows lack them. type: object required: - model - messages - inference_config properties: model: description: >- The model to run, narrowed to the one provider binding that fits this job's data plane. Rows written before the binding travelled with the job carry the bare model id as a string instead. oneOf: - $ref: '#/components/schemas/ModelInferenceRunModel' - type: string description: >- The Narrative model id alone, e.g. `anthropic.claude-sonnet-4.6`. messages: description: The conversation so far, oldest first. type: array items: $ref: '#/components/schemas/ModelInferenceRunMessage' inference_config: $ref: '#/components/schemas/ModelInferenceRunConfig' tools: description: >- Tool definitions offered to the model. Null when the job offers no tools, in which case the model only produces structured output. Never an empty array. type: - array - 'null' minItems: 1 items: $ref: '#/components/schemas/ModelInferenceRunToolSpec' tool_choice: description: >- How the model picks a tool. Only meaningful when `tools` is set; null leaves the provider default. oneOf: - $ref: '#/components/schemas/ModelInferenceRunToolChoice' - type: 'null' example: model: id: claude-sonnet-4 binding: provider: bedrock model_id: global.anthropic.claude-sonnet-4 capabilities: structured_output_mode: native messages: - role: user content: - type: text text: Which city? inference_config: output_format_schema: type: object max_tokens: 1024 temperature: null top_p: null stop_sequences: null thinking: null tools: null tool_choice: null ModelInferenceRunJobResult: description: >- The turn the model produced, with its provenance and token usage. Results written today carry every field below. `tool_calls`, `stop_reason`, `produced_blocks`, `final_answer_from` and `failed_structured_output` were added after this job type existed, so older rows carry only `structured_output` and `usage`. type: object required: - structured_output - usage properties: structured_output: description: >- The model's structured answer. Null on a tool-use-only turn, where the model called a tool instead of answering. type: - object - 'null' usage: $ref: '#/components/schemas/ModelInferenceRunUsage' tool_calls: description: Tool calls the model made on this turn. type: array items: $ref: '#/components/schemas/ModelInferenceRunToolCall' stop_reason: description: >- Why the model stopped. Unrecognised provider values are passed through verbatim. type: string examples: - end_turn - tool_use - max_tokens - stop_sequence - guardrail_intervened - content_filtered - malformed_model_output produced_blocks: description: >- The blocks the model produced, reasoning included, each with the id it was given. Empty on operators that do not report them — a reader then rebuilds the turn from the other fields. type: array items: $ref: '#/components/schemas/ModelInferenceRunProducedBlock' final_answer_from: description: Ids of the `produced_blocks` the answer was taken from. type: array items: type: string failed_structured_output: description: >- Structured output that did not satisfy `output_format_schema`. The job still succeeds and the raw output is kept here rather than discarded. oneOf: - $ref: '#/components/schemas/ModelInferenceRunFailedStructuredOutput' - type: 'null' example: structured_output: city: Paris usage: completion_tokens: 907 prompt_tokens: 4849 total_tokens: 5756 tool_calls: [] stop_reason: end_turn produced_blocks: [] final_answer_from: [] failed_structured_output: null DatasetsDeleteTableJobInput: type: object required: - external_id properties: external_id: description: The table's external identifier. type: string is_narrative_managed: description: >- Whether Narrative owns the table's storage. A table Narrative does not manage is deregistered rather than dropped. Added after this job type existed, so older rows lack the key. type: - boolean - 'null' example: external_id: nio_10736 is_narrative_managed: true DatasetsDeleteTableJobResult: description: Empty. The API records nothing beyond the job reaching `completed`. type: object example: {} DatasetsExecuteDmlJobInput: type: object required: - dataset_id - nql - compiled_sql properties: dataset_id: description: The dataset the statement runs against. type: integer format: int64 nql: description: The NQL statement as written. type: string compiled_sql: description: The SQL that `nql` compiles to. This is what the operator runs. type: string nio_last_modified_at: description: The `_nio_last_modified_at` watermark the statement writes. type: - string - 'null' format: date-time example: dataset_id: 10736 nql: DELETE FROM "company_data"."10736" WHERE "age" < 18 compiled_sql: DELETE FROM narrative.datasets.ds_10736 WHERE age < 18 nio_last_modified_at: null DatasetsExecuteDmlJobResult: description: >- Row counts for the statement. A job completed through the API carries `type` as well; one completed by the legacy executor does not. type: object required: - affected_rows - inserted_rows - updated_rows - deleted_rows properties: type: description: Repeated inside the result by the completion handler. type: string enum: - datasets_execute_dml affected_rows: type: integer format: int64 inserted_rows: type: integer format: int64 updated_rows: type: integer format: int64 deleted_rows: type: integer format: int64 example: type: datasets_execute_dml affected_rows: 10 inserted_rows: 0 updated_rows: 0 deleted_rows: 10 DatasetsCreateTableJobInput: type: object required: - dataset_id - compiled_sql properties: dataset_id: description: The dataset the table is created for. type: integer compiled_sql: description: The `CREATE TABLE` statement, compiled by the API. type: string example: dataset_id: 10736 compiled_sql: CREATE TABLE narrative.datasets.ds_10736 (age BIGINT) DatasetsCreateTableJobResult: description: Empty. The API records nothing beyond the job reaching `completed`. type: object example: {} DatasetsTruncateTableJobInput: type: object required: - dataset_id properties: dataset_id: description: The dataset being truncated. type: integer example: dataset_id: 10736 DatasetsTruncateTableJobResult: description: Empty. The API records nothing beyond the job reaching `completed`. type: object example: {} DatasetsEnforceTableTtlRetentionPolicyJobInput: type: object required: - dataset_id properties: dataset_id: description: The dataset the policy applies to. type: integer format: int64 dataset_external_id: description: The dataset's external identifier. Null when the dataset has none. type: - string - 'null' example: dataset_id: 10736 dataset_external_id: nio_10736 DatasetsEnforceTableTtlRetentionPolicyJobResult: description: Empty. The API records nothing beyond the job reaching `completed`. type: object example: {} DatasetsEnforceRowTtlRetentionPolicyJobInput: type: object required: - dataset_id - sql properties: dataset_id: description: The dataset the policy applies to. type: integer sql: description: The delete statements that enforce the policy, run in order. type: array items: type: string example: dataset_id: 10736 sql: - >- DELETE FROM narrative.datasets.ds_10736 WHERE _nio_last_modified_at < 1706400000000 DatasetsEnforceRowTtlRetentionPolicyJobResult: description: Empty. The API records nothing beyond the job reaching `completed`. type: object example: {} DatasetsCalculateAffectedRowsJobInput: type: object required: - compiled_sql - dataset_id properties: compiled_sql: description: The SELECT that counts the rows, compiled by the API. type: string dataset_id: description: The dataset being counted. type: integer format: int64 example: compiled_sql: SELECT COUNT(1) AS affected_rows FROM narrative.datasets.ds_10736 dataset_id: 10736 DatasetsCalculateAffectedRowsJobResult: description: >- The operator's raw SELECT output. The count sits at `rows[0].values.affected_rows`; the job carries the generic select result rather than a count field of its own so that new SELECT-backed job types need no operator change. A job completed through the API carries `type` as well; one completed by the legacy executor does not. type: object required: - rows properties: type: description: The operator that produced the result, not the job's own type. type: string enum: - datasets_execute_select rows: type: array items: $ref: '#/components/schemas/DatasetsCalculateAffectedRowsRow' example: type: datasets_execute_select rows: - values: affected_rows: 42 ModelTrainingRunJobInput: type: object required: - company_id - dataset_id - instance_type - base_model_id - base_model_repository - base_model_repo_id - trained_model_narrative_repository_model_id - trained_model_narrative_repo_id - trained_model_version - trained_model properties: company_id: description: The company the trained model belongs to. type: integer format: int64 connections: description: >- Destinations the trained model is delivered to once training finishes. Null when there are none; absent on jobs enqueued before the field existed. type: - array - 'null' items: $ref: '#/components/schemas/ModelTrainingRunConnection' custom_axolotl_config_override: description: >- Overrides merged into the generated Axolotl training config. Null to use the defaults. type: - object - 'null' dataset_id: description: The dataset the model trains on. type: integer format: int64 instance_type: description: The instance the training runs on, e.g. `ml.g5.12xlarge`. type: string base_model_id: description: The base model being fine-tuned. type: integer format: int64 base_model_repository: $ref: '#/components/schemas/ModelTrainingRunRepository' base_model_repo_id: description: >- The base model's id within its repository, e.g. `meta-llama/Llama-3.1-8B`. type: string trained_model_narrative_repository_model_id: description: >- The id the trained model is published under in Narrative's repository. type: string format: uuid trained_model_narrative_repo_id: description: >- The trained model's full repository path, `//`. type: string trained_model_version: description: The version this run produces. type: integer trained_model: $ref: '#/components/schemas/ModelTrainingRunOutputModel' example: company_id: 1 connections: null custom_axolotl_config_override: null dataset_id: 10736 instance_type: ml.g5.12xlarge base_model_id: 57 base_model_repository: type: hugging_face organization: meta-llama base_model_repo_id: meta-llama/Llama-3.1-8B trained_model_narrative_repository_model_id: 7d2f1b3c-5e6a-4f8b-9c0d-1e2f3a4b5c6d trained_model_narrative_repo_id: 1/7d2f1b3c-5e6a-4f8b-9c0d-1e2f3a4b5c6d/1 trained_model_version: 1 trained_model: name: churn-predictor collaborators: view: type: none train: type: none deploy: type: none description: null tags: null license_id: null JobResult: description: >- A job result the spec does not describe a shape for. The server stores `result` as arbitrary JSON and does not constrain it, so this is any JSON value. Null until the job reaches a terminal state. examples: - row_count: 100 - {} ModelsDeliverModelJobInput: type: object required: - company_id - app_id - connection_id - profile_id - model_id - model_name - model_version properties: company_id: description: The company that owns the model. type: integer format: int64 app_id: description: The app being delivered to. type: integer format: int64 connection_id: description: The connection being delivered to. type: string format: uuid profile_id: description: The destination profile within the app. type: string format: uuid model_id: description: The model's id in Narrative's repository. type: string format: uuid model_name: type: string model_version: type: integer quick_settings: description: >- Connector settings for the destination. Null when the connection needs none. type: - object - 'null' example: company_id: 1 app_id: 142 connection_id: 0f1e2d3c-4b5a-4968-9788-6a5b4c3d2e1f profile_id: 9c1f0a2e-3d4b-4c5a-8e6f-7a8b9c0d1e2f model_id: 7d2f1b3c-5e6a-4f8b-9c0d-1e2f3a4b5c6d model_name: churn-predictor model_version: 1 quick_settings: null JobInput: description: >- A job input the spec does not describe a shape for. The server stores `input` as arbitrary JSON and does not constrain it, so this is any JSON value. examples: - dataset_id: 10736 compiled_sql: SELECT `t`.`age` FROM narrative.datasets.ds_10736 `t` - {} HealthCheckJobInput: description: >- Empty. The job carries no parameters — the data plane it targets is the job's own `data_plane_id`. type: object example: {} JobId: type: string format: uuid description: Unique identifier for the job. RequestSource: description: >- Who asked for the job. Discriminated by `type`: `api_user` for a job requested through the API on behalf of a user, `process` for one enqueued by a Narrative process. oneOf: - $ref: '#/components/schemas/ApiUserRequestSource' - $ref: '#/components/schemas/ProcessRequestSource' discriminator: propertyName: type mapping: api_user: $ref: '#/components/schemas/ApiUserRequestSource' process: $ref: '#/components/schemas/ProcessRequestSource' State: description: >- Where a job is in its lifecycle. - `pending` — enqueued and waiting to be picked up. - `scheduled` — claimed by an executor but not yet started. - `running` — being executed. - `pending_cancellation` — cancellation has been requested and the data plane has yet to stop the work. - `completed`, `cancelled`, `failed` — terminal states. type: string enum: - pending - scheduled - running - pending_cancellation - completed - cancelled - failed ExecutionClusterType: description: |- The type of the execution cluster to run the job on. - `dedicated` runs job on a dedicated cluster. - `shared` runs job on a shared cluster. type: string enum: - dedicated - shared MaterializeViewJobPartition: description: One partition expression applied to the written table. type: object required: - field - fn - args properties: field: description: The column the partition is derived from. type: string fn: description: The partition transform, e.g. `day` or `bucket`. type: string args: description: Arguments to `fn`. Empty for transforms that take none. type: array items: type: string example: field: event_timestamp fn: day args: [] MaterializeViewJobChunkMetadata: description: Which chunk of a batched refresh this job is. type: object required: - batch_id - chunk_sequence properties: batch_id: description: Shared by every chunk of the same refresh. type: string format: uuid chunk_sequence: type: object required: - number - of properties: number: description: This chunk's position in the batch, starting at 1. type: integer of: description: How many chunks the batch has. type: integer example: batch_id: 0f1e2d3c-4b5a-4968-9788-6a5b4c3d2e1f chunk_sequence: number: 1 of: 4 MaterializeViewJobDeltaDatasetBound: description: The upper bound of the rows a DELTA source contributes to this refresh. type: object required: - dataset_id properties: dataset_id: type: integer format: int64 upper_bound: description: >- Inclusive `_nio_last_modified_at` upper bound. Null when the dataset has no data. type: - string - 'null' format: date-time example: dataset_id: 10674 upper_bound: '2024-01-28T00:00:00Z' MaterializeViewJobRowStats: type: object required: - affected_rows - inserted_rows - updated_rows - deleted_rows properties: affected_rows: type: integer format: int64 inserted_rows: type: integer format: int64 updated_rows: type: integer format: int64 deleted_rows: type: integer format: int64 NqlForecastJobSuccess: type: object required: - success properties: success: type: object required: - result properties: result: type: object required: - Forecast properties: Forecast: type: object required: - rows - cost properties: rows: description: How many rows the query would return. type: integer cost: description: What those rows would cost, in microcents. type: integer example: success: result: Forecast: rows: 1643721216 cost: 136130662400000 NqlForecastJobFailure: type: object required: - failure properties: failure: type: object required: - msg properties: msg: description: Why the forecast could not be produced. type: string example: failure: msg: query timed out DatasetsCalculateColumnStatsJobInputV2: description: Pre-compiled SQL. The API compiles the query; the operator just runs it. type: object required: - dataset_id - compiled_sql properties: dataset_id: description: The dataset the statistics are computed for. type: integer format: int64 compiled_sql: description: The SELECT that produces the statistics. type: string example: dataset_id: 10736 compiled_sql: SELECT `ds_10674`.`age` FROM narrative.datasets.ds_10674 `ds_10674` DatasetsCalculateColumnStatsJobInputV1: description: >- Per-column instructions. The operator builds the query from these. `enabled_column_stats` was added after this shape existed; the oldest rows carry only `dataset_id`. type: object required: - dataset_id properties: dataset_id: description: The dataset the statistics are computed for. type: integer format: int64 enabled_column_stats: description: >- Which statistics to collect, keyed by column name. Null when the job was enqueued without any. type: - object - 'null' additionalProperties: $ref: '#/components/schemas/DatasetsCalculateColumnStatsColumnDetails' example: dataset_id: 10736 enabled_column_stats: AGE: data_type: long enabled_column_stats: nan_value_count: false null_value_count: true value_count: true lower_bound: true upper_bound: true column_stored_bytes: true approx_count_distinct: false count_distinct: false histogram: false mean: false standard_deviation: false completeness: false observed_types: false CollectAccessRulesBillingDataSource: type: object required: - access_rule_id - rows - price_per_row properties: access_rule_id: description: The access rule the rows came from. type: integer format: int64 rows: description: How many rows this access rule contributed. type: integer format: int64 price_per_row: $ref: '#/components/schemas/CollectAccessRulesBillingDataPrice' ModelInferenceRunModel: description: >- The model, narrowed to the one provider binding that fits this job's data plane. type: object required: - id - binding properties: id: description: The Narrative model id. type: string binding: $ref: '#/components/schemas/ModelInferenceRunProviderBinding' ModelInferenceRunMessage: type: object required: - role - content properties: role: type: string enum: - user - assistant - system content: description: The turn's content blocks, in order. type: array items: $ref: '#/components/schemas/ContentBlock' ModelInferenceRunConfig: description: >- Sampling settings for the call. Every key is present; the optional ones are null when unset. `thinking` was added after this job type existed, so older rows lack it. type: object required: - output_format_schema properties: output_format_schema: description: JSON Schema the model's structured output must satisfy. type: object max_tokens: type: - integer - 'null' temperature: type: - number - 'null' format: float top_p: type: - number - 'null' format: float stop_sequences: type: - array - 'null' items: type: string thinking: description: >- Reasoning setting for the call. Null leaves the binding's own default. oneOf: - $ref: '#/components/schemas/ModelInferenceRunThinkingSetting' - type: 'null' ModelInferenceRunToolSpec: description: >- One tool definition, shaped to map straight onto the provider's tool specification. type: object required: - name - description - input_schema properties: name: type: string description: type: string input_schema: description: JSON Schema for the tool's arguments. type: object strict: description: >- Opt into grammar-constrained sampling for this tool's arguments. Defaults to true when the field is absent, which is how payloads written before the field existed decode. type: boolean default: true ModelInferenceRunToolChoice: description: >- How the model selects a tool. `auto` lets it decide, `any` forces some tool, `specific_tool` forces the named one. type: object required: - type properties: type: type: string enum: - auto - any - specific_tool name: description: >- Which tool to call. Present only when `type` is `specific_tool`; must match a `tools[].name`. type: string examples: - type: auto - type: specific_tool name: nio_emit_structured_output ModelInferenceRunUsage: type: object required: - completion_tokens - prompt_tokens - total_tokens properties: completion_tokens: type: integer prompt_tokens: type: integer total_tokens: type: integer ModelInferenceRunToolCall: type: object required: - id - name - arguments properties: id: type: string name: type: string arguments: description: The arguments the model produced for the call. type: object ModelInferenceRunProducedBlock: type: object required: - id - block properties: id: description: The block's identifier, e.g. `b_c08cf800_00`. type: string block: $ref: '#/components/schemas/ContentBlock' ModelInferenceRunFailedStructuredOutput: type: object required: - message - raw_output properties: message: description: Why the output was rejected. type: string raw_output: description: What the model actually produced. DatasetsCalculateAffectedRowsRow: type: object required: - values properties: values: description: One returned row, keyed by column name. type: object ModelTrainingRunConnection: description: One destination the trained model is delivered to. type: object required: - app_id - profile_id properties: app_id: description: The app being delivered to. type: integer format: int64 profile_id: description: The destination profile within the app. type: string format: uuid quick_settings: description: >- Connector settings for the destination. Null when the connection needs none. type: - object - 'null' example: app_id: 142 profile_id: 9c1f0a2e-3d4b-4c5a-8e6f-7a8b9c0d1e2f quick_settings: null ModelTrainingRunRepository: description: Where a model lives. Discriminated by `type`. oneOf: - $ref: '#/components/schemas/ModelTrainingRunHuggingFaceRepository' - $ref: '#/components/schemas/ModelTrainingRunNarrativeRepository' discriminator: propertyName: type mapping: hugging_face: $ref: '#/components/schemas/ModelTrainingRunHuggingFaceRepository' narrative: $ref: '#/components/schemas/ModelTrainingRunNarrativeRepository' ModelTrainingRunOutputModel: description: What the run publishes. type: object required: - name - collaborators properties: name: type: string collaborators: $ref: '#/components/schemas/ModelTrainingRunCollaborators' description: type: - string - 'null' tags: type: - array - 'null' items: type: string license_id: type: - string - 'null' ApiUserRequestSource: type: object required: - type - company_id - user_id properties: type: type: string enum: - api_user company_id: description: The company the request was made for. type: integer format: int64 user_id: description: The user who made the request. type: integer format: int64 example: type: api_user company_id: 1 user_id: 1248 ProcessRequestSource: type: object required: - type - name properties: type: type: string enum: - process name: description: >- The process that enqueued the job, e.g. `narrative-control-plane` or `health-check`. type: string example: type: process name: narrative-control-plane DatasetsCalculateColumnStatsColumnDetails: type: object required: - data_type - enabled_column_stats properties: data_type: description: The column's type, as the stats job sees it. type: string enum: - boolean - double - long - string - timestamp_tz - array - object enabled_column_stats: $ref: '#/components/schemas/DatasetsCalculateColumnStatsFlags' CollectAccessRulesBillingDataPrice: type: object required: - currency - microcents properties: currency: description: ISO 4217 currency code. type: string examples: - USD microcents: description: Price per row, in microcents. type: integer format: int64 ModelInferenceRunProviderBinding: description: >- Where the model runs and what it can do there. Discriminated by `provider`. type: object required: - provider - model_id - capabilities properties: provider: type: string enum: - bedrock - snowflake_cortex model_id: description: >- The provider's own id for the model, e.g. `global.anthropic.claude-sonnet-4-6`. type: string capabilities: $ref: '#/components/schemas/ModelInferenceRunCapabilities' ContentBlock: description: >- A single block inside a message. Messages carry an ordered list of blocks. Five variants discriminated by `type`: - `text` — plain text content. The dominant variant for user messages and final assistant answers. - `tool_use` — the model requesting a tool call. Carries the call's `tool_use_id` (used to match it with the subsequent result), the fully-aliased `name`, and the `arguments` the model produced. - `tool_result` — the response to a `tool_use`. References the same `tool_use_id` and carries nested content blocks with the actual result text. `is_error` flags tool failures so the model can decide how to react. - `reasoning` — the model's own working, present on an assistant turn when the run asked for thinking (`defaults.thinking`). It comes **first** in the turn, ahead of the answer. `text` is optional: some models return their reasoning as words, others return only a `signature` and keep the words to themselves. - `redacted_reasoning` — reasoning the provider encrypted rather than returned. Opaque base64; there is nothing to read, and it exists so a turn can still be replayed intact. The discriminator field is `type`. Use it to dispatch in your client. Each block may also carry an **`id`** alongside its own fields (`b__`), the identifier it was given where it was produced. Blocks a caller sent, and turns stored before ids existed, have none. `final_answer_from` on the message points at ids, which is how a reader knows which block to render as the reply — see the note there. Reasoning blocks are passed through as the model produced them, `signature` included. A client that wants to continue a conversation exactly as the model left it can send them back verbatim; one that only wants to show the answer can drop them. The signature is meaningful only to the provider — treat it as opaque and don't parse it. oneOf: - title: Text type: object required: - type - text properties: id: type: string description: >- The id this block was produced under, when we produced it. Absent on blocks a caller sent and on turns stored before ids existed. example: b_c08cf800_01 type: type: string enum: - text text: type: string example: type: text text: What is 2 + 2? - title: ToolUse type: object required: - type - tool_use_id - name - arguments properties: id: type: string description: >- The id this block was produced under, when we produced it. Absent on blocks a caller sent and on turns stored before ids existed. example: b_c08cf800_01 type: type: string enum: - tool_use tool_use_id: type: string description: >- Server-assigned identifier the model produced when emitting the tool call. Use this to match a `tool_result` with its `tool_use`, and to fill `outputs[].tool_use_id` when resuming a `requires_action` run. example: tooluse_DWXPKZ50JDGib5GmShyUgJ name: type: string description: >- Fully-aliased tool name (`{alias}-{tool_name}`) — the same string the model saw in its tool catalog. The alias prefix is how the platform routes the call back to its definition. example: docs-search_narrative_i_o_knowledge_base arguments: type: object description: >- Arguments object produced by the model. Must conform to the tool's `input_schema` — if the model produced something that doesn't validate, the run terminates with the [MCP Tool Argument Validation Failed](https://docs.narrative.io/reference/architecture/agent-conversations/errors/mcp-tool-validation) error for server-side tools, or surfaces in `pending_tool_calls` as-is for client-side tools. example: query: rate limiting - title: ToolResult type: object required: - type - tool_use_id - content - is_error properties: id: type: string description: >- The id this block was produced under, when we produced it. Absent on blocks a caller sent and on turns stored before ids existed. example: b_c08cf800_01 type: type: string enum: - tool_result tool_use_id: type: string description: >- The `tool_use_id` from the matching `tool_use` block on the prior assistant turn. example: tooluse_DWXPKZ50JDGib5GmShyUgJ content: type: array description: >- Nested content blocks carrying the actual result. Almost always a single `text` block; the platform splits long results into multiple text blocks when the underlying MCP server returns multiple chunks. items: $ref: '#/components/schemas/ContentBlock' is_error: type: boolean description: >- Whether the tool call failed. The model decides how to react to errors — retry, ask the user, fall through to a partial answer, etc. Note that an MCP server returning a non-2xx response that the platform can still parse counts as `is_error: false` (the tool *succeeded* in returning a result, even if that result reports an underlying failure). - title: Reasoning type: object required: - type - signature properties: id: type: string description: >- The id this block was produced under, when we produced it. Absent on blocks a caller sent and on turns stored before ids existed. example: b_c08cf800_01 type: type: string enum: - reasoning text: type: string description: >- The model's working, when it returns it as words. Absent when the model reasoned but withheld the text — the Opus models do this, and `signature` is then the only evidence the turn reasoned at all. Never assume this field is present. example: Cleo cannot be Monday, so the only assignment left is… signature: type: string description: >- Provider-issued signature over the reasoning. Opaque: not a hash you can verify or a token you can decode. Send the block back unchanged to continue a turn as the model left it, or ignore it. example: CAIS6QMKcAgQEAEYAipATBOWJItj3lNDm2ZmBW70v+WJ5oI6W68N… example: type: reasoning signature: CAIS6QMKcAgQEAEYAipATBOWJItj3lNDm2ZmBW70v+WJ5oI6W68N… - title: RedactedReasoning type: object required: - type - data properties: id: type: string description: >- The id this block was produced under, when we produced it. Absent on blocks a caller sent and on turns stored before ids existed. example: b_c08cf800_01 type: type: string enum: - redacted_reasoning data: type: string description: >- Base64 of the encrypted reasoning. Nothing to display. Kept so the turn can be replayed whole. example: ZW5jcnlwdGVkLXJlYXNvbmluZy1ieXRlcw== example: type: redacted_reasoning data: ZW5jcnlwdGVkLXJlYXNvbmluZy1ieXRlcw== ModelInferenceRunThinkingSetting: description: >- What to ask the provider for: no thinking (`"disabled"`), thinking at an effort level, or thinking with a token budget. oneOf: - type: string enum: - disabled - type: object required: - type - level properties: type: type: string enum: - effort level: $ref: '#/components/schemas/ModelInferenceRunEffortLevel' - type: object required: - type - budget_tokens properties: type: type: string enum: - budget budget_tokens: type: integer minimum: 1024 examples: - disabled - type: effort level: high - type: budget budget_tokens: 2048 ModelTrainingRunHuggingFaceRepository: type: object required: - type - organization properties: type: type: string enum: - hugging_face organization: description: The Hugging Face organization the model sits under. type: string ModelTrainingRunNarrativeRepository: type: object required: - type - company_id properties: type: type: string enum: - narrative company_id: description: The company whose Narrative repository holds the model. type: integer format: int64 ModelTrainingRunCollaborators: description: Who may view, train on, and deploy the trained model. type: object required: - view - train - deploy properties: view: $ref: '#/components/schemas/ModelTrainingRunViewCollaboratorRule' train: $ref: '#/components/schemas/ModelTrainingRunCollaboratorRule' deploy: $ref: '#/components/schemas/ModelTrainingRunCollaboratorRule' DatasetsCalculateColumnStatsFlags: description: >- Which statistics to collect for one column. The first six are basic statistics, on by default; the rest are advanced and are turned on by the dataset's metrics configuration. Statistics that make no sense for the column's type are switched off before the job is enqueued — `mean` on a string column, for instance. type: object required: - nan_value_count - null_value_count - value_count - lower_bound - upper_bound - column_stored_bytes - approx_count_distinct - count_distinct - histogram - mean - standard_deviation - completeness - observed_types properties: nan_value_count: type: boolean null_value_count: type: boolean value_count: type: boolean lower_bound: type: boolean upper_bound: type: boolean column_stored_bytes: type: boolean approx_count_distinct: type: boolean count_distinct: type: boolean histogram: type: boolean mean: type: boolean standard_deviation: type: boolean completeness: type: boolean observed_types: type: boolean ModelInferenceRunCapabilities: description: >- What this provider binding supports. Only `structured_output_mode` is always sent — the rest are omitted entirely when unset, rather than sent as null. type: object required: - structured_output_mode properties: structured_output_mode: description: How the binding produces structured output. type: string enum: - native - forced_tool_use strict_tool_use: description: >- Present when the binding supports grammar-constrained tool arguments. type: object required: - max_tool_count properties: max_tool_count: description: How many strict tools one request may declare. type: integer supported_sampling_parameters: description: >- Which sampling parameters the binding honours. Absent when it accepts none; never an empty array. type: array minItems: 1 items: type: string enum: - temperature - top_p thinking_support: $ref: '#/components/schemas/ModelInferenceRunThinkingSupport' ModelInferenceRunEffortLevel: type: string enum: - low - medium - high ModelTrainingRunViewCollaboratorRule: description: >- One access rule. `all` and `none` stand alone; `inclusion` and `exclusion` list the companies they apply to. `anonymous` means no authentication is needed at all. type: object required: - type properties: type: type: string enum: - anonymous - all - none - inclusion - exclusion company_ids: description: >- The companies the rule names. Present only for `inclusion` and `exclusion`, and never empty. type: array minItems: 1 items: type: integer format: int64 examples: - type: none - type: inclusion company_ids: - 1 - 2 ModelTrainingRunCollaboratorRule: description: >- One access rule. `all` and `none` stand alone; `inclusion` and `exclusion` list the companies they apply to. type: object required: - type properties: type: type: string enum: - all - none - inclusion - exclusion company_ids: description: >- The companies the rule names. Present only for `inclusion` and `exclusion`, and never empty. type: array minItems: 1 items: type: integer format: int64 examples: - type: none - type: inclusion company_ids: - 1 - 2 ModelInferenceRunThinkingSupport: description: >- What a caller may ask this binding for about thinking, and what it is sent when nobody asks. Absent on a binding that is not offered thinking. type: object required: - vocabularies - reasoning_text_readable properties: vocabularies: description: >- The ways this binding can be asked to think, preferred one first. Never empty. type: array minItems: 1 items: $ref: '#/components/schemas/ModelInferenceRunThinkingVocabulary' unasked: $ref: '#/components/schemas/ModelInferenceRunThinkingSetting' description: >- The setting sent when a caller names none. Omitted for a binding that needs no thinking field at all. reasoning_text_readable: description: >- Whether the reasoning that comes back is readable text, rather than a signature with no words. type: boolean example: vocabularies: - type: effort levels: - low - medium - high default: medium unasked: disabled reasoning_text_readable: true ModelInferenceRunThinkingVocabulary: description: >- One way of asking a model to think, with the value used when a caller names the vocabulary without a value. Discriminated by `type`. oneOf: - $ref: '#/components/schemas/ModelInferenceRunThinkingEffortVocabulary' - $ref: '#/components/schemas/ModelInferenceRunThinkingBudgetVocabulary' discriminator: propertyName: type mapping: effort: $ref: '#/components/schemas/ModelInferenceRunThinkingEffortVocabulary' budget: $ref: '#/components/schemas/ModelInferenceRunThinkingBudgetVocabulary' ModelInferenceRunThinkingEffortVocabulary: type: object required: - type - levels - default properties: type: type: string enum: - effort levels: description: The effort levels the model accepts, shallowest first. Never empty. type: array minItems: 1 items: $ref: '#/components/schemas/ModelInferenceRunEffortLevel' default: $ref: '#/components/schemas/ModelInferenceRunEffortLevel' ModelInferenceRunThinkingBudgetVocabulary: type: object required: - type - default properties: type: type: string enum: - budget default: description: >- The token budget used when a caller asks for budgeted thinking without naming one. type: integer minimum: 1024 securitySchemes: BearerAuth: type: http scheme: bearer ````