---
title: "GET /v2/custom-actions/{custom_action_id}/"
method: GET
path: "/v2/custom-actions/{custom_action_id}/"
tags: ["blueprints_Custom Actions API"]
---

# GET /v2/custom-actions/{custom_action_id}/

`GET /v2/custom-actions/{custom_action_id}/`

⚠️ Linux only. Custom actions apply exclusively to Linux-managed devices. This endpoint is not applicable to Android, iOS, or Windows devices.

Retrieves the full details of a specific custom action by its unique ID.
Returns a CustomActionRead object containing the action's name, type, state, blueprint and device placement, display properties, options (with script references), and audit fields including created_by, updated_by, created_at, and updated_at. Use this endpoint to inspect a custom action's current configuration and retrieve its associated script_id values before modifying or deploying it.

**About Retrieve Custom Action**

Custom actions are operator-defined scripts surfaced on Linux devices through Blueprint settings or device Quick Actions. The CustomActionRead response includes each option's scripts.linux.script_id — a UUID referencing the script content stored externally. To retrieve the actual script content, use GET /v2/scripts/{script_id}/ with that UUID.

**Key Fields**

custom_action_id — UUID of the custom action to retrieve (path parameter, required)

id — UUID of the custom action in the response body

state — Current lifecycle state: draft, active, or inactive

options[*].scripts.linux.script_id — UUID reference to the script content; use with GET /v2/scripts/{script_id}/ to fetch the actual script

position_in_blueprints / position_in_device_settings — Where this action is surfaced in Blueprint and device UI

created_at / updated_at — Audit timestamps

**Common Use Cases**

Inspect a custom action's current state and placement before deciding to activate or deactivate it

Retrieve script_id values from the options to fetch and review the associated scripts

Confirm that a custom action's properties labels and messages are correctly set before deploying it in a Blueprint

**Best Practices**

Use this endpoint before calling PUT /v2/custom-actions/{custom_action_id}/ to understand the current state of the action

Cross-reference script_id values with GET /v2/scripts/{script_id}/ to verify script content is correct before activating the action

Check the state field to confirm whether the action is eligible for deployment (active) before including it in a Blueprint

**Workflow**

Obtain the custom_action_id from GET /v2/custom-actions/ or from the Console

Call GET /v2/custom-actions/{custom_action_id}/ to retrieve the full action object

Review state, options, and placement fields

If needed, use the script_id from each option's scripts.linux object to inspect the script content via GET /v2/scripts/{script_id}/

## Path parameters

- `custom_action_id` string, uuid, required

## Response `200`

Success

- object
  - `content` BlueprintsCustomActionRead
    - `name` string, required — Custom Action name
    - `type` 'button' | 'toggle' | 'radio' | 'dropdown', required — The UI component type for this custom action
    - `state` 'draft' | 'active' | 'inactive', required — The current operational state of the custom action. Only active custom actions can be deployed to Linux devices.
    - `position_in_blueprints` 'none' | 'blueprints_apps_and_configuration' | 'blueprints_connectivity' | 'blueprints_device_security' | 'blueprints_display_and_branding' | 'blueprints_esper_settings' | 'blueprints_scripts' | 'blueprints_files' | 'blueprints_platform_services' | 'blueprints_hardware_settings' | 'blueprints_sound' | 'blueprints_system_updates' | 'blueprints_time_and_date', required — The location in the blueprint where the custom action will be added
    - `position_in_device_settings` 'none' | 'device_quick_settings', required — The location in the device's Quick Actions where the custom action will be added
    - `properties` object, required — Object for the description, info_message, and tooltip_message.
    - `id` string, uuid, required — Unique identifier for the custom action
    - `options` BlueprintsOptionsResponse[], required — List of options for the custom action
      - `label` string, required — Label shown on the UI
      - `key` string, uuid, required — Unique key identifier for the option
      - `scripts` object, required — Platform-specific script references. Currently only Linux platform is supported. Platform key must be lowercase "linux".
        - `linux` BlueprintsPlatformScriptResponse, required
          - `script_id` string, uuid, required — Script identifier stored in external storage
    - `created_at` string, date-time, required — When the custom action was created
    - `updated_at` string, date-time, required — When the custom action was last updated
    - `created_by` integer, required — User ID who created the custom action
    - `updated_by` integer, required — User ID who last updated the custom action
  - `message` string
  - `code` 200

## Other responses

- `404` — Custom Action not found

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/revisions/e1f64cbb488e/schema)