Home

REST API

Unravel's REST API allows you to query and collect data from your cluster, using either HTTP or HTTPS protocol. The API returns information similar to what you see in Unravel UI. All requests and responses are in JSON format.

Authentication

  • If you're running the API through Unravel UI's Manage | API, authenticate through the UI; be sure to select the correct protocol (HTTPS or HTTP).

  • Authenticate through the /signIn request.

Your access level is determined by your RBAC role. Unravel Server returns a session token which you then include in all subsequent requests.

Base URL

All endpoints are relative to the base URL, http://unravel-host:3000/api/v1 or https://unravel-host:3000/api/v1

Methods

The API adheres to the standard create-read-update-delete (CRUD) semantics in which the request path defines the endpoint, and the method specifies the action to perform on the resource.

Method

Action

POST

Creates a resource.

GET

Retrieves a resource.

PUT

Updates or edits a resource.

DELETE

Deletes a resource.

Endpoints

Endpoint

Description

/signIn

Authenticates your API session and gets a token which you include in all requests in this session.

/apps/search

Gets all apps filtered by app type, status, username, queue, and tags.

/apps/{app_id}/resource_usage

Gets average number of jobs by type.

/apps/{app_id}/tags

Gets tags for a given app.

/apps/events/inefficient_apps

Gets total job count per status in a given time window (at one hour intervals).

/apps/resources/cpu/allocated

Gets a time series for CPU allocattions by app type.

/apps/resources/memory/allocated

Gets a time series for allocated memory by app type.

/apps/status/finished

Gets a time series of finished apps.

/apps/status/running

Gets a list of running apps.

/yarn_rm/kill_app

Gets the status code for a killed YARN app.

/yarn_rm/move_app

Gets the status code for a moved YARN app.

/common/app/{app_id}/summary

Gets a summary of a given app.

/common/app/{app_id}/errors

Gets the errors associated with a given app.

/common/app/{app_id}/extendedsummary

Gets a detailed summary of a given app.

/common/app/{app_id}/logs

Gets the logs associated with a given app.

/common/app/{app_id}/recommendation

Gets Unravel's recommendations for the given application.

spark/{clusterUid}/{app_id}/{attempt_id}/errorview

Gets the status of a given app.

/reports/files/reports/latest?reportType=huge_files

/reports/celeryreports

Under construction.

/reports/data/diskusage/capacity_task_details

Under construction.

/reports/data/diskusage/get_latest_reports?task_name=capacity_prediction_task

/reports/data/diskusage/get_latest_reports?task_name=cloud_mappings_grouped_reports_task

/reports/data/diskusage/get_latest_reports?task_name=cloud_reports_task

/reports/data/diskusage/get_latest_reports?task_name=cluster_discovery_task

/reports/data/diskusage/get_latest_reports?task_name=queue_analysis_task

/reports/data/diskusage/get_latest_reports?task_name=small_files_report

/reports/data/diskusage/get_latest_reports?task_name=topx_report

/reports/data/diskusage/get_latest_success_reports?task_name=cloud_mappings_grouped_reports_task

/reports/data/diskusage/get_latest_success_reports?task_name=cloud_reports_task

/reports/data/diskusage/get_latest_success_reports?task_name=cluster_discovery_task

/reports/data/diskusage/get_latest_success_reports?task_name=queue_analysis_task

/reports/data/diskusage/get_latest_success_reports?task_name=topx_report

/reports/data/kpis

Generates a Key Performance Indicator (KPI) report.

/reports/data/small_file_report_details

Gets details about the small file report.

/reports/celeryreports/metadata

Under construction.

/reports/clusteroptimization/metadata

Under construction.

/reports/archives/get_report_archives

Under construction.

/reports/files/reports/latest?reportType=empty_files

/reports/files/reports/latest?reportType=medium_files

/reports/files/reports/latest?reportType=tiny_files

/reports/operational/clusterstats?st={timestamp}&et={timestamp}&mode={summary_type}

/reports/operational/clusterworkload?gte={timestamp}&lte={timestamp}&reportBy={interval}

/reports/queueanalysis/get_latest_report_by_queue_name

/reports/schedules

Under construction.

/chargeback/cb/app?gte={date}&lte={date}

Gets chargeback reports by application type. Gives the count of all applications in all queues for all users across all clusters.

/chargeback/cb/appt/queue

Gets chargeback reports by queue.

/chargeback/cb/appt/user?gte={date}&lte={date}

Gets chargeback reports by user.

/celery/analyze-queue-data

Generates a Queue Analysis report.

/celery/cloud-mappings-grouped-reports

Generates a Cloud Mapping grouped report.

/celery/cloud-mappings-reports

Generates a Cloud Mappping report.

/celery/cloud_reports/cloud_providers

Generates a report on cloud providers.

/celery/cluster-discovery

Generates a Cluster Discovery report.

/celery/generate_cluster_app_param_report

Generates a cluster app parameter report.

/celery/predict_capacity

Generates a Forecasting report.

/celery/small-files-report

Gets the Small Files report.

/autoactions

Gets a list of all active and inactive AutoActions.

/autoactions/recent_violations

Gets a list of recent AutoAction violations.

/autoactions/metrics

Gets a list of AutoAction metrics.

/autoactions/recent_violations?eventType=AAVA

Gets a list of recent AutoAction violations filtered by app type.

/autoactions/templates?is_enabled=true&is_admin=true

Gets a list of Unravel's predefined AutoAction templates.

/jobs

Gets total job count, at one hour intervals.

/jobs/count

Gets the number of jobs in a given timeframe, grouped by state, app type, user, or queue.

/jobs/bystatus

Gets the total job count per job type, at one hour intervals, in a given time window.

/jobs/bytype

Gets the total job count per job type, at one hour intervals, in a given time window.

/clusters

Gets a list of clusters.

/clusters/nodes

Gets a summary of cluster nodes.

/clusters/resources/cpu/allocated

Gets a time series of CPU allocations across all clusters.

/clusters/resources/memory/allocated

Gets a time series of memory allocations across all clusters.

/clusters/resources/cpu/total

Gets total CPU usage across all clusters.

/clusters/resources/memory/total

Gets total memory usage across all clusters.

/clusters/{cluster_name}/resources/cpu/allocated

Gets a time series for allocated CPU in a given cluster.

/clusters/{cluster_name}/resources/memory/allocated

Gets a time series for allocated memory in a given cluster.

/clusters/{cluster_name}/resources/cpu/total

Gets a time series for total CPU usage in a given cluster.

/clusters/{cluster_name}/resources/memory/total

Gets a time series for total memory usage in a given cluster.

/clusters/{cluster_name}/nodes

Gets a time series of all the nodes of given cluster grouped by node state.

/elasticsearch/clusters/metrics

Returns the cluster level KPI metrics for Elasticsearch.

/elasticsearch/{cluster}/index

Returns indices and the corresponding metrics in an Elasticsearch cluster.

/elasticsearch/{cluster}/kpi_cluster

Returns the cluster level value of a specific metric.

/elasticsearch/{cluster}/kpi_index

Returns metric values of all the indices.

/elasticsearch/{cluster}/kpi_node

Returns the metric values of specific nodes

/elasticsearch/{cluster}/nodes

/kafka/brokers?cluster_id={cluster_name}&start_time={timestamp}&end_time={timestamp}

Gets a list of Kafka brokers active on a given cluster during a given timeframe.

/kafka/{cluster_name}/kpi?broker={broker_name}?start_time={timestamp}&end_time={timestamp}&interval={minutes}&prefix={metrics}

Gets KPIs for a given Kafka broker.

/kafka/{cluster_name}/kpi_clusters?start_time={timestamp}&end_time={timestamp}&interval={minutes}&prefix={metrics}

Gets KPIs for a given Kafka cluster.

/kafka/{cluster_name}/kpi_topics?start_time={timestamp}&end_time={timestamp}&interval={minutes}&prefix={metrics}

Gets KPIs for the Kafka topics within a given timespan.

/kafka/clusters?gte={timestamp}&lt={timestamp}

Gets Kafka cluster metrics.

/kafka/topics/partions/ts?cluster_id={cluster_name}?topic_id={topic_name}&start_time={timestamp}&end_time={timestamp}&interval={minutes}&metric_pattern={metric}

Gets details about a given partition.

/kibana/clusters/metrics

Returns Kibana KPI metrics.

/kibana/{cluster}/kpi_cluster

Returns cluster level metric values of Kibana.

/logstash/pipelines/{pipeline}/kpis

Returns the KPIs of a specific pipeline.

/logstash/nodes/kpis

Returns overall average KPIs of all nodes in logstash (events in and events out).

/logstash/nodes/list

Returns the list of nodes in the logstash.

/logstash/nodes/{node}/kpis

Returns the KPIs of a specific node.

/logstash/pipelines/kpis

Returns overall average KPIs for all pipelines in the logstash.

/logstash/pipelines/list

Returns the list of pipelines and their metrics in the logstash.

/logstash/pipelines/{pipeline}/kpis

Returns the KPIs of a specific pipeline.

/search/cb/appt?from={date}&to={date}

Gets chargeback reports per app type and the number of apps in all queues for all users across all clusters.

/search/cb/appt/user?from={date}&to={date}

Gets chargeback reports by application type for a specific queue.

/search/cb/appt/queue

Gets chargeback reports per queue.

/workflows

Lists all workflows.

Error codes

Unravel Server returns these HTTP error codes:

Error Code

Description

400

Invalid request parameters or malformed requests.

401

Authentication failure.

403

Authorization failure.

404

Object not found.

500

Internal API error.

503

Response is temporarily unavailable; try again later.