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.

/common/app/{app_id}/status

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/metrics

Gets a list of AutoAction metrics.

/autoactions/recent_violations

Gets a list of recent AutoAction violations.

/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.

/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.

/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.

/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.