> ## 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. # Trigger a health check > Enqueue a health check job for the specified data plane. Optionally target a specific compute pool. Returns the created job. ## OpenAPI ````yaml https://docs-cdn.narrative.io/api-reference/main/openapi.json post /data-planes/{data_plane_id}/health-check 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 finishes the token exchange and marks the connection `connected`. 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: API Access Token management - 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: 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 cost forecasts, data forecasts, 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: 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: Workflows description: >- The `workflows` API allows you to create, schedule, trigger, and archive workflows. Workflows are defined using a serverlessworkflow YAML specification. paths: /data-planes/{data_plane_id}/health-check: post: tags: - Data Planes summary: Trigger a health check description: >- Enqueue a health check job for the specified data plane. Optionally target a specific compute pool. Returns the created job. parameters: - name: data_plane_id in: path required: true schema: type: string format: uuid requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/EnqueueHealthCheckRequest' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/JobResponse' '404': description: Data plane not found security: - BearerAuth: [] components: schemas: EnqueueHealthCheckRequest: type: object properties: compute_pool_id: description: >- Optional compute pool to target for the health check. If omitted, the data plane's default compute pool is used. type: string format: uuid JobResponse: type: object required: - job_id - data_plane_id - request_source - state - type - input - executor - execution_cluster - failures - idempotency_key - result - created_at - updated_at - attempted_at - attempt_version - ended_at properties: job_id: $ref: '#/components/schemas/JobId' data_plane_id: description: The data plane the job runs on. type: string format: uuid compute_pool_id: description: The compute pool associated with the job, if any. type: string format: uuid request_source: $ref: '#/components/schemas/RequestSource' state: $ref: '#/components/schemas/State' type: description: >- The type associated with the job. Jobs can have a type of nql-forecast or materialize-view. type: string input: $ref: '#/components/schemas/Input' executor: description: The internal job executor tied to the job. type: string execution_cluster: $ref: '#/components/schemas/ExecutionClusterType' failures: description: causes of job failure type: array items: $ref: '#/components/schemas/Failure' idempotency_key: description: The unique ID associated with the job. type: string result: $ref: '#/components/schemas/Result' 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. type: string format: date-time example: job_id: 2a5b9ad7-dc8f-47bb-8e62-843a38f8054c data_plane_id: f79cbdae-4848-47ca-95e8-69588364d185 request_source: type: api_user company_id: 1 user_id: 407 state: completed type: materialize-view input: nql: >- CREATE MATERIALIZED VIEW "test_stats" AS SELECT "value" FROM "company_data"."10674" dataset_id: 10736 stats_enabled: true compiled_select: |- SELECT `ds_10674`.`value` FROM narrative.datasets.ds_10674 `ds_10674` executor: job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266 idempotency_key: >- 10736:29329c64e7b8a4eda86aaabe04872b832ab456b5543d0c259c812525391f158c:669a5f8e4f373c2f907700decde47511aac6470f5698e2b856fb07f09160e5f2 result: dataset_id: 10736 snapshot_id: 1724919539450264600 recalculation_id: abf9a2ec-426b-4751-bd16-fcb435061925 created_at: '2023-10-31T11:19:13.400498' updated_at: '2023-10-31T11:25:08.327209' attempted_at: '2023-10-31T11:19:13.400498' attempt_version: 1 ended_at: '2023-10-31T11:25:08.327194' JobId: type: string format: uuid description: Unique identifier for the job. RequestSource: type: object properties: type: description: The job request type. type: string company_id: description: The company associated with the job. type: integer user_id: description: The user associated with the job. type: integer example: type: api_user company_id: 1 user_id: 1248 State: type: string default: pending enum: - failed - cancelled - completed - pending - scheduled - pending_cancellation - running Input: oneOf: - $ref: '#/components/schemas/MaterializedViewInput' - $ref: '#/components/schemas/ExplainInput' 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 Failure: type: object properties: message: type: string timestamp: type: string format: date-time value: description: >- useful information to diagnostic a failure such as a Apache Spark stacktrace type: object Result: oneOf: - $ref: '#/components/schemas/MaterializedViewOutput' - $ref: '#/components/schemas/ExplainOutput' MaterializedViewInput: type: object properties: nql: description: The NQL associated with the job. type: string compiled_sql: description: The compiled SQL associated with the job. type: string dataset_id: description: >- The output dataset associated with a job that creates a materialized view. type: integer stats_enabled: description: >- A flag to indicate whether there are extended dataset statistics turned on for a materialized view. No flag passed in the api request will default to true. example: nql: | CREATE MATERIALIZED VIEW "sampleNQL" as WITH OrderedData AS ( SELECT "mobile_id_unique_identifier"."value" AS mobile_id, "timestamp_object"."day", "timestamp_object"."hour", "geographic_location"."latitude", "geographic_location"."longitude", "event_timestamp", LAG("event_timestamp", 1) OVER (PARTITION BY "mobile_id_unique_identifier"."value", "geographic_location"."latitude", "geographic_location"."longitude" ORDER BY "event_timestamp") AS prev_timestamp FROM "company_data"."6402" WHERE "mobile_id_unique_identifier"."value" IS NOT NULL ), ContinuousPresence AS ( SELECT mobile_id, "day", "hour", latitude, longitude, event_timestamp, prev_timestamp, CASE WHEN extract(minute FROM event_timestamp) - extract(minute FROM prev_timestamp) BETWEEN 40 AND 120 THEN 1 ELSE 0 END AS is_continuous FROM OrderedData ) SELECT mobile_id, "day", "hour", latitude, longitude FROM ContinuousPresence WHERE is_continuous = 1 GROUP BY mobile_id, "day", "hour", latitude, longitude dataset_id: 6404 stats_enabled: true compiled_sql: |- SELECT `t`.`mobile_id`, `t`.`day`, `t`.`hour`, `t`.`latitude`, `t`.`longitude` FROM (SELECT `ds_6402`.`mobile_id_unique_identifier`['value'] `mobile_id`, `ds_6402`.`timestamp_object`['day'] `day`, `ds_6402`.`timestamp_object`['hour'] `hour`, `ds_6402`.`geographic_location`['latitude'] `latitude`, `ds_6402`.`geographic_location`['longitude'] `longitude`, CASE WHEN EXTRACT(MINUTE FROM `ds_6402`.`event_timestamp`) - EXTRACT(MINUTE FROM LAG(`ds_6402`.`event_timestamp`, 1) OVER ( PARTITION BY `ds_6402`.`mobile_id_unique_identifier`.`value`, `ds_6402`.`geographic_location`.`latitude`, `ds_6402`.`geographic_location`.`longitude` ORDER BY `ds_6402`.`event_timestamp` NULLS LAST)) >= 40 AND EXTRACT(MINUTE FROM `ds_6402`.`event_timestamp`) - EXTRACT(MINUTE FROM LAG(`ds_6402`.`event_timestamp`, 1) OVER ( PARTITION BY `ds_6402`.`mobile_id_unique_identifier`.`value`, `ds_6402`.`geographic_location`.`latitude`, `ds_6402`.`geographic_location`.`longitude` ORDER BY `ds_6402`.`event_timestamp` NULLS LAST)) <= 120 THEN 1 ELSE 0 END `is_continuous` FROM narrative.datasets.ds_6402 `ds_6402`) `t` WHERE `t`.`is_continuous` = 1 GROUP BY `t`.`mobile_id`, `t`.`day`, `t`.`hour`, `t`.`latitude`, `t`.`longitude` ExplainInput: type: object properties: nql: description: The NQL associated with the job. type: string compiled_sql: description: The compiled SQL associated with the job. type: string example: nql: >- EXPLAIN SELECT narrative.rosetta_stone."age", narrative.rosetta_stone."unique_id"."value" FROM narrative.rosetta_stone WHERE narrative.rosetta_stone._price_cpm_usd <= 10.00 AND narrative.rosetta_stone."age" > 50 compiled_sql: |- SELECT SUM(CASE WHEN `t17`.`_dataset_id` IN (192, 544) THEN `t17`.`_access_rule`['price_micro_cents_usd'] * 128 WHEN `t17`.`_dataset_id` IN (63, 73, 280) THEN `t17`.`_access_rule`['price_micro_cents_usd'] * 1024 WHEN `t17`.`_dataset_id` = 477 THEN `t17`.`_access_rule`['price_micro_cents_usd'] * 8192 ELSE `t17`.`_access_rule`['price_micro_cents_usd'] END) `totalCost`, SUM(CASE WHEN `t17`.`_dataset_id` IN (192, 544) THEN 128 WHEN `t17`.`_dataset_id` IN (63, 73, 280) THEN 1024 WHEN `t17`.`_dataset_id` = 477 THEN 8192 ELSE 1 END) `totalRows` FROM (SELECT `t`.`age`, NAMED_STRUCT('id', 623, 'price_micro_cents_usd', 100000) `_access_rule`, 63 `_dataset_id` FROM (SELECT `ds_63`.`_nio_sample_1024`, `ds_63`.`age` FROM narrative.datasets.ds_63 `ds_63`) `t` WHERE `t`.`_nio_sample_1024` UNION ALL SELECT `t2`.`age`, NAMED_STRUCT('id', 105, 'price_micro_cents_usd', 0) `_access_rule`, 73 `_dataset_id` FROM (SELECT `ds_73`.`_nio_sample_1024`, `ds_73`.`age` FROM narrative.datasets.ds_73 `ds_73`) `t2` WHERE `t2`.`_nio_sample_1024` UNION ALL SELECT NULL `age`, NAMED_STRUCT('id', 4, 'price_micro_cents_usd', 1000) `_access_rule`, 192 `_dataset_id` FROM (SELECT `ds_192`.`_nio_sample_128` FROM narrative.datasets.ds_192 `ds_192`) `t5` WHERE `t5`.`_nio_sample_128` UNION ALL SELECT `t8`.`age`, NAMED_STRUCT('id', 58, 'price_micro_cents_usd', 200000) `_access_rule`, 280 `_dataset_id` FROM (SELECT `ds_280`.`_nio_sample_1024`, `ds_280`.`age` FROM narrative.datasets.ds_280 `ds_280`) `t8` WHERE `t8`.`_nio_sample_1024` UNION ALL SELECT FLOOR(DATEDIFF(CURRENT_DATE, CAST(TO_TIMESTAMP(`t11`.`yob`) AS DATE)) / 365) `age`, NAMED_STRUCT('id', 108, 'price_micro_cents_usd', 0) `_access_rule`, 477 `_dataset_id` FROM (SELECT `ds_477`.`_nio_sample_8192`, `ds_477`.`yob` FROM narrative.datasets.ds_477 `ds_477`) `t11` WHERE `t11`.`_nio_sample_8192` UNION ALL SELECT `t14`.`age_in_2_year_ranges_enhanced` `age`, NAMED_STRUCT('id', 463, 'price_micro_cents_usd', 0) `_access_rule`, 544 `_dataset_id` FROM (SELECT `ds_544`.`_nio_sample_128`, `ds_544`.`age_in_2_year_ranges_enhanced` FROM narrative.datasets.ds_544 `ds_544`) `t14` WHERE `t14`.`_nio_sample_128`) `t17` WHERE `t17`.`_access_rule`['price_micro_cents_usd'] <= 1000000 AND `t17`.`age` > 50 MaterializedViewOutput: type: object description: The output of a materialized view. properties: dataset_id: description: >- The output dataset associated with a job that creates a materialized view. type: integer snapshot_id: description: The snapshot ID associated with the job. type: integer recalculation_id: description: The recalculation ID associated with the job. type: string example: dataset_id: 6404 snapshot_id: 739881302291276700 recalculation_id: abf9a2ec-426b-4751-bd16-fcb435061925 ExplainOutput: type: object description: The output of a forecast. properties: success: type: object properties: result: type: object properties: Forecast: type: object properties: cost: type: integer description: >- The cost to buy every row of data available in the forecast on a CPM basis. rows: type: integer description: The amount of rows returned from a forecast. example: success: result: Forecast: cost: 136130662400000 rows: 1643721216 securitySchemes: BearerAuth: type: http scheme: bearer ````