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.

To test the REST API, navigate to the Manage | API tab in Unravel UI.

Authentication

Log into Unravel UI.
Authenticate from your command line. Your access level is determined by your role. Unravel Server returns a session token which you use for 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

Resource	Method	Endpoint	Description
	POST	/signIn	To use the REST API, log into Unravel UI and send the POST /signIn request.
apps	POST	/apps/search	Gets all apps filtered by app type, status, username, queue, and tags.
	GET	/apps/{app_id}/resource_usage	Gets average number of jobs by type.
	GET	/apps/{app_id}/tags	Gets tags for a given app.
	GET	/apps/events/inefficient_apps	Gets total job count per status in a given time window (at one hour intervals).
	GET	/apps/resources/cpu/allocated	Gets a time series for CPU allocattions by app type.
	GET	/apps/resources/memory/allocated	Gets a time series for allocated memory by app type.
	GET	/apps/status/finished	Gets a time series of finished apps.
	GET	/apps/status/running	Gets a list of running apps.
yarn_rm	GET	/yarn_rm/kill_app	Gets the status code for a killed YARN app.
	GET	/yarn_rm/move_app	Gets the status code for a moved YARN app.
common	GET	/common/app/{app_id}/summary	Gets a summary of a given application.
	GET	/common/app/{app_id}/errors	Gets the errors associated with a given application.
	GET	/common/app/{app_id}/extendedsummary	Under construction.
	GET	/common/app/{app_id}/logs	Gets the logs associated with a given application.
	GET	/common/app/{app_id}/recommendation	Gets Unravel's recommendations for the given application.
	GET	/common/app/{app_id}/status	Gets the status of a given application.
reports	GET	/reports/files/reports/latest?reportType=huge_files
	GET	/reports/celeryreports	Under construction.
	GET	/reports/data/diskusage/capacity_task_details	Under construction.
	GET	/reports/data/diskusage/get_latest_reports?task_name=capacity_prediction_task
	GET	/reports/data/diskusage/get_latest_reports?task_name=cloud_mappings_grouped_reports_task
	GET	/reports/data/diskusage/get_latest_reports?task_name=cloud_reports_task
	GET	/reports/data/diskusage/get_latest_reports?task_name=cluster_discovery_task
	GET	/reports/data/diskusage/get_latest_reports?task_name=queue_analysis_task
	GET	/reports/data/diskusage/get_latest_reports?task_name=small_files_report
	GET	/reports/data/diskusage/get_latest_reports?task_name=topx_report
	GET	/reports/data/diskusage/get_latest_success_reports?task_name=cloud_mappings_grouped_reports_task
	GET	/reports/data/diskusage/get_latest_success_reports?task_name=cloud_reports_task
	GET	/reports/data/diskusage/get_latest_success_reports?task_name=cluster_discovery_task
	GET	/reports/data/diskusage/get_latest_success_reports?task_name=queue_analysis_task
	GET	/reports/data/diskusage/get_latest_success_reports?task_name=topx_report
	GET	/reports/data/kpis	Under construction.
	GET	/reports/data/small_file_report_details	Gets details about the small file report.
	GET	/reports/celeryreports/metadata	Under construction.
	GET	/reports/clusteroptimization/metadata	Under construction.
	GET	/reports/archives/get_report_archives	Under construction.
	GET	/reports/files/reports/latest?reportType=empty_files
	GET	/reports/files/reports/latest?reportType=medium_files
	GET	/reports/files/reports/latest?reportType=tiny_files
	GET	/reports/operational/clusterstats?st={timestamp}&et={timestamp}&mode={summary_type}
	GET	/reports/operational/clusterworkload?gte={timestamp}&lte={timestamp}&reportBy={interval}
	GET	/reports/queueanalysis/get_latest_report_by_queue_name
	GET	/reports/queueanalysis/get_latest_report_by_queue_names
	GET	/reports/schedules	Under construction.
chargeback	GET	/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.
	GET	/chargeback/cb/appt/queue	Gets chargeback reports by queue.
	GET	/chargeback/cb/appt/user?gte={date}&lte={date}	Gets chargeback reports by user.
celery	GET	/celery/analyze-queue-data	Under construction.
	GET	/celery/cloud-mappings-grouped-reports	Under construction.
	GET	/celery/cloud-mappings-reports	Under construction.
	GET	/celery/cloud_reports/cloud_providers	Under construction.
	GET	/celery/cluster-discovery	Under construction.
	GET	/celery/generate_cluster_app_param_report	Under construction.
	GET	/celery/predict_capacity	Under construction.
	GET	/celery/small-files-report	Gets the small file report.
autoactions	GET	/autoactions	Gets a list of active and inactive auto actions.
	GET	/autoactions/metrics	Gets a list of auto action metrics.
	GET	/autoactions/recent_violations	Gets a list of recent auto action violations.
jobs	GET	/jobs	Gets total job count, at one hour intervals.
	GET	/jobs/count	Gets the number of jobs in a given timeframe, grouped by state, application type, user, or queue.
	GET	/jobs/bystatus	Gets the total job count per job type, at one hour intervals, in a given time window.
	GET	/jobs/bytype	Gets the total job count per job type, at one hour intervals, in a given time window.
clusters	GET	/clusters	Gets a list of clusters.
	GET	/clusters/nodes	Gets a summary of cluster nodes.
	GET	/clusters/resources/cpu/allocated	Gets a time series of CPU allocations across all clusters.
	GET	/clusters/resources/memory/allocated	Gets a time series of memory allocations across all clusters.
	GET	/clusters/resources/cpu/total	Gets total CPU usage across all clusters.
	GET	/clusters/resources/memory/total	Gets total memory usage across all clusters.
	GET	/clusters/{cluster_name}/resources/cpu/allocated	Gets a time series for allocated CPU in a given cluster.
	GET	/clusters/{cluster_name}/resources/memory/allocated	Gets a time series for allocated memory in a given cluster.
	GET	/clusters/{cluster_name}/resources/cpu/total	Gets a time series for total CPU usage in a given cluster.
	GET	/clusters/{cluster_name}/resources/memory/total	Gets a time series for total memory usage in a given cluster.
	GET	/clusters/{cluster_name}/nodes	Gets a time series of all the nodes of given cluster grouped by node state.
kafka	GET	/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.
	GET	/kafka/{cluster_name}/kpi?broker={broker_name}?start_time={timestamp}&end_time={timestamp}&interval={minutes}&prefix={metrics}	Gets KPIs for a given Kafka broker.
	GET	/kafka/{cluster_name}/kpi_clusters?start_time={timestamp}&end_time={timestamp}&interval={minutes}&prefix={metrics}	Gets KPIs for a given Kafka cluster.
	GET	/kafka/{cluster_name}/kpi_topics?start_time={timestamp}&end_time={timestamp}&interval={minutes}&prefix={metrics}	Gets KPIs for a given Kafka topic.
	GET	/kafka/clusters?gte={timestamp}&lt={timestamp}	Gets Kafka cluster metrics.
	GET	/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.
search	GET	/search/cb/appt?from={date}&to={date}	Gets chargeback reports by application type. Gives the count of all applications in all queues for all users across all clusters.
	GET	/search/cb/appt/user?from={date}&to={date}	Gets chargeback reports by user.
	GET	/search/cb/appt/queue	Gets chargeback reports by queue.
workflows	GET	/workflows	Lists all workflows.
	GET	/workflows/missing_sla	Lists workflows with missed SLA.

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.

In this section:

Home