# pai-workload Part of **PAI** # Platform for AI (PAI) Workload Management ## Capabilities Overview | Sub-capability | Calling Mode | Description | |----------------|--------------|-------------| | Get Workload Information | Synchronous | Retrieve detailed information about specific workloads. | ## API Calling Patterns ### Authentication The PAI Workload Management API uses Alibaba Cloud AccessKey-based authentication. - Include the following headers in your request: ```text Authorization: acs : x-acs-signature-method: HMAC-SHA1 x-acs-signature-version: 1.0 x-acs-date: ``` - Set your credentials via environment variables: ```bash export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret ``` - While RAM role-based authentication is supported in some contexts, AccessKey is the primary method for direct API calls and is recommended for most integrations. ### Service Endpoint APIs use a region-specific endpoint pattern: ```text https://pai-workload..aliyuncs.com ``` Common regions include: - `cn-hangzhou` - `cn-shanghai` - `cn-beijing` Replace `` with your target deployment region. ### Synchronous Request Pattern All workload queries follow a synchronous request-response flow: 1. Send an HTTP GET or POST request to the appropriate endpoint with query or body parameters. 2. The server validates the request and authenticates the caller. 3. If valid, the server returns a complete JSON response with workload metadata immediately. 4. No polling or async handling is required—results are returned in a single round trip. Use standard HTTP clients or the Alibaba Cloud SDK to make these calls. ## Parameter Reference ### Get Workload Information | Parameter | Type | Required | Default | Constraints | Description | |----------|------|----------|---------|-------------|-------------| | WorkloadId | string | false | — | — | The unique, system-generated ID for the workload. | | WorkloadName | string | false | — | — | The user-defined name of the workload. | | WorkloadType | string | false | — | — | The type of the workload. | | WorkspaceId | string | false | — | — | The ID of the workspace that contains the workload. | | WorkspaceName | string | false | — | — | The name of the workspace that contains the workload. | | WorkloadCreatedTime | string | false | — | — | The creation time of the workload, in UTC format. | | WorkloadStatus | string | false | — | one of: Pending, Running, Succeeded, Failed | The current status of the workload. | | UserId | string | false | — | — | The ID of the user who created the workload. | | TenantId | string | false | — | — | The ID of the tenant that contains the workload. | | UserName | string | false | — | — | The name of the user who created the workload. | | Priority | integer | false | — | — | The scheduling priority of the workload. A higher value indicates a higher priority. | | IsScheduled | string | false | — | one of: true, false | Specifies whether the workload is scheduled. | | QueueMetas | array | false | — | — | A list of metadata for the queues associated with the workload. | > **Note**: At least one identifying parameter (e.g., `WorkloadId` or `WorkloadName` + `WorkspaceId`) should be provided to retrieve meaningful results. ## Code Examples ### List Workload by ID - Python - cn-hangzhou ```python from alibabacloud_pai_workload20240101.client import Client from alibabacloud_tea_openapi import models as open_api_models def create_client(access_key_id, access_key_secret, region_id='cn-hangzhou'): config = open_api_models.Config( access_key_id=access_key_id, access_key_secret=access_key_secret, region_id=region_id ) return Client(config) client = create_client( access_key_id=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'), access_key_secret=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET') ) response = client.get_workload_info( workload_id='wl-1234567890abcdef' ) print(response.body) ``` ### Query Workload by Name and Workspace - Java - cn-shanghai ```java import com.aliyun.paiworkload20240101.Client; import com.aliyun.teaopenapi.models.Config; public class WorkloadExample { public static void main(String[] args) throws Exception { Config config = new Config() .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")) .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")) .setRegionId("cn-shanghai"); Client client = new Client(config); var request = new GetWorkloadInfoRequest() .setWorkloadName("my-training-job") .setWorkspaceId("ws-abcdef123456"); var response = client.getWorkloadInfo(request); System.out.println(response.getBody()); } } ``` ### Get Workload Status via cURL - Bash - cn-beijing ```bash #!/bin/bash ACCESS_KEY_ID="$ALIBABA_CLOUD_ACCESS_KEY_ID" ACCESS_KEY_SECRET="$ALIBABA_CLOUD_ACCESS_KEY_SECRET" REGION="cn-beijing" WORKLOAD_ID="wl-abcdef1234567890" # Construct canonical request and sign (simplified; use SDK in production) TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ") ENDPOINT="https://pai-workload.${REGION}.aliyuncs.com" curl -X GET "${ENDPOINT}/workloads/${WORKLOAD_ID}" \ -H "x-acs-date: ${TIMESTAMP}" \ -H "Authorization: acs ${ACCESS_KEY_ID}:$(echo -n "GET\n\n\n${TIMESTAMP}\n/${WORKLOAD_ID}" | openssl dgst -sha1 -hmac "${ACCESS_KEY_SECRET}" -binary | base64)" ``` ### Filter Workloads by Status - Python - cn-hangzhou ```python import os from alibabacloud_pai_workload20240101.client import Client from alibabacloud_tea_openapi import models as open_api_models config = open_api_models.Config( access_key_id=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'), access_key_secret=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'), region_id='cn-hangzhou' ) client = Client(config) # Note: Filtering by status may require listing all workloads and filtering client-side # if the API doesn't support server-side status filtering directly. response = client.list_workloads(workspace_id='ws-123456') workloads = response.body.workloads running_jobs = [w for w in workloads if w.workload_status == 'Running'] print(f"Found {len(running_jobs)} running workloads") ``` ## Response Format ```json { "WorkloadId": "wl-1234567890abcdef", "WorkloadName": "image-classification-training", "WorkloadType": "TrainingJob", "WorkloadStatus": "Running", "WorkloadCreatedTime": "2024-06-15T08:30:00Z", "WorkspaceId": "ws-abcdef123456", "WorkspaceName": "vision-workspace", "UserId": "1234567890123456", "TenantId": "t-9876543210", "UserName": "alice@example.com", "Priority": 10, "IsScheduled": "false", "QueueMetas": [ { "QueueId": "q-xyz789", "QueueName": "gpu-queue" } ] } ``` **Key Fields**: - `WorkloadId` — Unique identifier for the workload; use for precise lookups - `WorkloadStatus` — Current execution state; critical for monitoring - `WorkloadCreatedTime` — Timestamp for auditing and lifecycle tracking - `WorkspaceId` — Contextual container for resource isolation - `Priority` — Indicates scheduling precedence relative to other workloads - `QueueMetas` — Shows which resource queues the workload is assigned to ## Error Handling This API does not define domain-specific error codes in the extracted documentation. Standard Alibaba Cloud API errors apply (e.g., `InvalidAccessKeyId`, `SignatureDoesNotMatch`, `Forbidden.RAM`). Handle these using general Alibaba Cloud error patterns. ### Rate Limits & Retry No rate limit information was provided in the source documentation. Follow general Alibaba Cloud best practices: - Implement exponential backoff (e.g., 1s, 2s, 4s delays) on 429/5xx responses - Respect the `Retry-After` header if present - Cache non-sensitive workload metadata to reduce call frequency ## Environment Requirements - Install the official SDK: ```bash pip install alibabacloud_pai_workload20240101 ``` - Set credentials as environment variables: ```bash export ALIBABA_CLOUD_ACCESS_KEY_ID=your_key_id export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_key_secret ``` - Requires Python 3.6+ or Java 8+ ## FAQ Q: Can I query workloads without specifying a WorkloadId? A: Yes, you can use other identifiers like `WorkloadName` combined with `WorkspaceId` or `TenantId`. However, providing `WorkloadId` yields the most precise and efficient lookup. Q: What values can WorkloadStatus have? A: Valid statuses are: `Pending`, `Running`, `Succeeded`, and `Failed`. These reflect the execution lifecycle of the workload. Q: Is there a way to list all workloads in a workspace? A: While the documented function focuses on retrieving specific workload info, listing typically requires a separate `ListWorkloads` API (not detailed here). Check the full PAI API reference for listing capabilities. Q: How do I interpret the Priority field? A: Higher integer values indicate higher scheduling priority. Workloads with priority 20 will be scheduled before those with priority 10, all else being equal. Q: Are QueueMetas always populated? A: `QueueMetas` is populated only when the workload is associated with one or more resource queues (e.g., GPU or CPU queues). It may be empty or null for workloads not yet scheduled. ## Pricing & Billing ### Billing Model Billing is based on a per-request model. ### Free Tier No free tier information was provided in the source documentation. ### Usage Limits No usage limits (e.g., QPS, max results) were specified in the extracted data. ### Billing Notes Since this is a metadata query API, costs are typically negligible compared to compute-intensive PAI services. However, each API call counts toward your billable request volume.