> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/concepts/resources/nilus/observability/api-endpoints.md). # API Endpoints Nilus Manager exposes a small set of read-only HTTP endpoints for checking service health and inspecting pipeline runs, statistics, and CDC state. This page documents the endpoints intended for external use. ## Base URL and authentication * API base path: `https:///nilus-manager/api/v1` * Tenant-scoped base path: `https:///nilus-manager/api/v1/tenants/` * All requests require `Authorization: Bearer `. ## Authentication notes * Swagger and ReDoc live under `/nilus-manager/docs` and `/nilus-manager/redoc`. * The separate metrics server is for Prometheus scraping and does not use the same interactive API auth flow. All endpoints below are `GET` requests. ## Main monitoring endpoints These endpoints live under the API base path. | Endpoint | Description | | ------------------------------ | ------------------------------------------------------------------------------- | | `/nilus-manager/api/v1/health` | Health check. Reports whether the service and its backing database are healthy. | | `/nilus-manager/api/v1/info` | Returns service identity and image/version metadata. | ## Tenant-scoped external APIs These endpoints live under the tenant-scoped base path. | Endpoint | Description | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/tenants/{tenant}/pipelines` | Lists all pipelines. Supported filters: `run_as_user`, `is_success`, `resource_id`, `started_at`, `started_at_gte`, `started_at_lte`, `limit`, `offset`. Paginated responses include a `total` count of records matching the filters. | | `/tenants/{tenant}/pipelines/{resource_id}/runs` | Lists pipeline runs for a specific DataOS resource id. Paginated responses include a `total` count. | | `/tenants/{tenant}/pipelines/{resource_id}/stats` | Returns lean run statistics for a specific DataOS resource id over a `period` such as `24h` or `7d`. | ### Paginated list responses `pipelines` and `runs` return a `total` field alongside `limit` and `offset` so UIs can render accurate pagination: ```json { "pipelines": [], "limit": 50, "offset": 0, "total": 1342 } ``` ### Stats response The stats endpoint returns high-level run health and timing only. There is intentionally no `total_records_processed` field, because "processed" is ambiguous across extracted, normalized, loaded, retried, and skipped records. ```json { "resource_id": "...", "period": "30d", "period_start": "...", "period_end": "...", "stats": { "total_runs": 42, "successful_runs": 40, "failed_runs": 2, "success_rate": 95.24, "avg_duration_sec": 83.5, "max_duration_sec": 210.0 } } ``` ## CDC Offset | Endpoint | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/tenants/{tenant}/cdc/offset-storage` | Lists persisted CDC offset records. Supported filters: `resource_id`, `connector_name`, `offset_key`, `record_insert_ts_gte`, `record_insert_ts_lte`, `limit`, `offset`. | ## CDC Schema History | Endpoint | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/tenants/{tenant}/cdc/schema-history` | Lists persisted CDC schema-history records. Supported filters: `resource_id`, `connector_name`, `record_insert_ts_gte`, `record_insert_ts_lte`, `limit`, `offset`. | ## Example ```bash curl -H "Authorization: Bearer " \ "https:///nilus-manager/api/v1/tenants//pipelines?resource_id=my-resource&limit=20" ``` ## Internal runtime APIs These endpoints support Nilus runtime behavior and state persistence rather than general external use. They live under `/nilus-manager/api/v1/tenants/`. | Endpoint | Method | Description | | ------------------------------------------------- | ------ | -------------------------------------------------------- | | `/pipeline/runs` | `POST` | Stores pipeline-run metadata. | | `/pipeline/{pipeline_name}/state` | `GET` | Returns the latest successful pipeline state. | | `/pipeline/{pipeline_name}/state` | `POST` | Stores pipeline state. | | `/pipeline/{pipeline_name}/offsets` | `GET` | Returns the latest CDC offsets for a pipeline. | | `/pipeline/{pipeline_name}/offsets` | `POST` | Stores CDC offsets for a pipeline. | | `/pipeline/{pipeline_name}/schema-history` | `GET` | Returns stored CDC schema history. | | `/pipeline/{pipeline_name}/schema-history/exists` | `GET` | Checks whether schema history exists. | | `/pipeline/{pipeline_name}/schema-history` | `POST` | Stores CDC schema history. | | `/storage/health` | `GET` | Checks health of the backing storage used for CDC state. | ## Metrics server endpoints These endpoints live on the separate metrics server, which defaults to port `9090`. | Endpoint | Method | Description | | ------------------------------ | ------ | ------------------------------- | | `http://:9090/metrics` | `GET` | Prometheus metrics payload. | | `http://:9090/health` | `GET` | Metrics-server health check. | | `http://:9090/readiness` | `GET` | Metrics-server readiness probe. | ## Notes * Use `resource_id` in pipeline filters and paths. Do not rely on older `dataos_resource_id` wording. * `period` for the stats endpoint is resource-scoped and expects a value like `24h`, `7d`, or `30d`. ## Related docs * [Understanding Nilus Manager](/concepts/resources/nilus/concepts/architecture-and-mechanism.md) * [Exposed Prometheus Metrics](/concepts/resources/nilus/observability/prometheus-metrics.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/concepts/resources/nilus/observability/api-endpoints.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.