> For the complete documentation index, see [llms.txt](https://docs.vagon.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vagon.io/teams/reference/usages.md).

# Usages

## List Total Account Usage

> Get account/organization level usage information in minutes.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`usage\_minutes\` | Integer | Available usage in minutes |\
> \| \`machine\_type\` | String | Machine type name (e.g., "Planet") |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
>     "usage\_minutes": 2669,\
>     "machine\_type": "Planet",\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-02-04T13:26:14Z"\
> }\
> \
>  \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/usage":{"get":{"summary":"List Total Account Usage","responses":{"200":{"description":"Account usage information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Usages"],"description":"Get account/organization level usage information in minutes.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `usage_minutes` | Integer | Available usage in minutes |\n| `machine_type` | String | Machine type name (e.g., \"Planet\") |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### **Success Response Example**\n\n``` json\n{\n    \"usage_minutes\": 2669,\n    \"machine_type\": \"Planet\",\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T13:26:14Z\"\n}\n\n ```"}}},"components":{"schemas":{"UsageResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","description":"Organization-level usage information","properties":{"usage_minutes":{"type":"integer","description":"Available usage time in minutes"},"machine_type":{"type":"string","description":"Machine type for usage calculation"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## List All Machines Usage

> Get remaining usage information in minutes for all machines.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`machines\` | Array | Array of machine usage objects |\
> \| \`machines\[].machine\_id\` | Integer | Machine ID |\
> \| \`machines\[].machine\_name\` | String | Machine Name |\
> \| \`machines\[].usage\_minutes\` | Integer | Usage minutes based on total balance (including credits) |\
> \| \`machines\[].machine\_type\` | String | Machine type name (e.g., "Planet") |\
> \| \`machines\[].usage\_source\` | String | Usage source - "machine" (only assigned usages) or "team\_balance" (can use team balance when no additional usage on machine) |\
> \| \`count\` | Integer | Total number of machines |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
>     "machines": \[\
>         {\
>             "machine\_id": 512,\
>             "machine\_name": "Computer #512",\
>             "usage\_minutes": 0,\
>             "machine\_type": "Planet",\
>             "usage\_source": "machine"\
>         },\
>         {\
>             "machine\_id": 509,\
>             "machine\_name": "Computer #509",\
>             "usage\_minutes": 0,\
>             "machine\_type": "Planet",\
>             "usage\_source": "machine"\
>         }\
>     ],\
>     "count": 2,\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-01-28T08:46:22Z"\
> }\
> \
>  \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/usage/machines":{"get":{"summary":"List All Machines Usage","responses":{"200":{"description":"Machine usage list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineUsageListResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Usages"],"description":"Get remaining usage information in minutes for all machines.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `machines` | Array | Array of machine usage objects |\n| `machines[].machine_id` | Integer | Machine ID |\n| `machines[].machine_name` | String | Machine Name |\n| `machines[].usage_minutes` | Integer | Usage minutes based on total balance (including credits) |\n| `machines[].machine_type` | String | Machine type name (e.g., \"Planet\") |\n| `machines[].usage_source` | String | Usage source - \"machine\" (only assigned usages) or \"team_balance\" (can use team balance when no additional usage on machine) |\n| `count` | Integer | Total number of machines |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### **Success Response Example**\n\n``` json\n{\n    \"machines\": [\n        {\n            \"machine_id\": 512,\n            \"machine_name\": \"Computer #512\",\n            \"usage_minutes\": 0,\n            \"machine_type\": \"Planet\",\n            \"usage_source\": \"machine\"\n        },\n        {\n            \"machine_id\": 509,\n            \"machine_name\": \"Computer #509\",\n            \"usage_minutes\": 0,\n            \"machine_type\": \"Planet\",\n            \"usage_source\": \"machine\"\n        }\n    ],\n    \"count\": 2,\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-01-28T08:46:22Z\"\n}\n\n ```"}}},"components":{"schemas":{"MachineUsageListResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","description":"Usage information for all machines","properties":{"machines":{"type":"array","items":{"$ref":"#/components/schemas/MachineUsageItem"}},"count":{"type":"integer","description":"Total number of machines"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"MachineUsageItem":{"type":"object","description":"Usage information for a single machine","properties":{"machine_id":{"type":"integer","description":"Machine ID"},"machine_name":{"type":"string","description":"Machine name"},"usage_minutes":{"type":"integer","description":"Remaining usage in minutes"},"machine_type":{"type":"string","description":"Machine performance type"},"usage_source":{"type":"string","enum":["machine","team_balance"],"description":"\"machine\" means only assigned usages; \"team_balance\" means can use team balance when no additional usage on machine."}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## List Machine Usages by ID

> Get remaining machine usage information in minutes for a specific machine.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Parameter | Type | Description |\
> \| --- | --- | --- |\
> \| \`id\`\\\* | Integer | Machine ID |\
> \
> \### \*\*Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`machine\_id\` | Integer | Machine ID |\
> \| \`machine\_name\` | String | Machine name |\
> \| \`usage\_minutes\` | Integer | Usage minutes based on total balance (including credits) |\
> \| \`machine\_type\` | String | Machine type friendly name (e.g., "Planet") |\
> \| \`usage\_source\` | String | Usage source - "machine" (only assigned usages) or "team\_balance" (can use team balance when no additional usage on machine) |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
>     "machine\_id": 717,\
>     "machine\_name": "Computer #717",\
>     "usage\_minutes": 1172,\
>     "machine\_type": "Planet",\
>     "usage\_source": "machine",\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-02-04T13:28:19Z"\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request |\
> \| 404 | Machine not found |\
> \| 4709 | Seat not found for machine |\
> \| 4710 | Permission required |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/usage/machines/{id}":{"get":{"summary":"List Machine Usages by ID","responses":{"200":{"description":"Machine usage information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineUsageResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4709":{"description":"Seat not found for machine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4709Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Usages"],"description":"Get remaining machine usage information in minutes for a specific machine.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Parameter | Type | Description |\n| --- | --- | --- |\n| `id`\\* | Integer | Machine ID |\n\n### **Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `machine_id` | Integer | Machine ID |\n| `machine_name` | String | Machine name |\n| `usage_minutes` | Integer | Usage minutes based on total balance (including credits) |\n| `machine_type` | String | Machine type friendly name (e.g., \"Planet\") |\n| `usage_source` | String | Usage source - \"machine\" (only assigned usages) or \"team_balance\" (can use team balance when no additional usage on machine) |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### **Success Response Example**\n\n``` json\n{\n    \"machine_id\": 717,\n    \"machine_name\": \"Computer #717\",\n    \"usage_minutes\": 1172,\n    \"machine_type\": \"Planet\",\n    \"usage_source\": \"machine\",\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T13:28:19Z\"\n}\n\n ```\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request |\n| 404 | Machine not found |\n| 4709 | Seat not found for machine |\n| 4710 | Permission required |"}}},"components":{"schemas":{"MachineUsageResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","description":"Usage information for a specific machine","properties":{"machine_id":{"type":"integer","description":"Machine ID"},"machine_name":{"type":"string","description":"Machine name"},"usage_minutes":{"type":"integer","description":"Remaining usage in minutes"},"machine_type":{"type":"string","description":"Machine performance type"},"usage_source":{"type":"string","enum":["machine","team_balance"],"description":"\"machine\" means only assigned usages; \"team_balance\" means can use team balance when no additional usage on machine."}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4709Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Assign Machine Usage

> Assign usage in minutes from team balance to a machine.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Body Parameters\*\*\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`machine\_id\`\\\* | Integer | Yes | Machine ID |\
> \| \`minutes\`\\\* | Integer | Yes | Number of minutes to assign |\
> \
> \### Request Body Example\
> \
> \`\`\` json\
> {\
>   "machine\_id": 717,\
>   "minutes": 1\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`assigned\_minutes\` | Integer | Number of minutes assigned |\
> \| \`machine\_id\` | Integer | Machine ID that received the assignment |\
> \| \`machine\_type\` | String | Machine type friendly name used for pricing calculation (e.g., "Planet") |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
>     "assigned\_minutes": 1,\
>     "machine\_id": 717,\
>     "machine\_type": "Planet",\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-02-04T13:31:47Z"\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request (missing required parameters) |\
> \| 404 | Machine not found |\
> \| 480 | Insufficient organization balance |\
> \| 482 | Balance assignment failed |\
> \| 4710 | Permission required |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/usage/assign":{"post":{"summary":"Assign Machine Usage","responses":{"200":{"description":"Usage assigned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignUsageResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"480":{"description":"Insufficient organization balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error480Response"}}}},"482":{"description":"Balance assignment failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error482Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Usages"],"description":"Assign usage in minutes from team balance to a machine.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Body Parameters**\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `machine_id`\\* | Integer | Yes | Machine ID |\n| `minutes`\\* | Integer | Yes | Number of minutes to assign |\n\n### Request Body Example\n\n``` json\n{\n  \"machine_id\": 717,\n  \"minutes\": 1\n}\n\n ```\n\n### **Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `assigned_minutes` | Integer | Number of minutes assigned |\n| `machine_id` | Integer | Machine ID that received the assignment |\n| `machine_type` | String | Machine type friendly name used for pricing calculation (e.g., \"Planet\") |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### **Success Response Example**\n\n``` json\n{\n    \"assigned_minutes\": 1,\n    \"machine_id\": 717,\n    \"machine_type\": \"Planet\",\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T13:31:47Z\"\n}\n\n ```\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request (missing required parameters) |\n| 404 | Machine not found |\n| 480 | Insufficient organization balance |\n| 482 | Balance assignment failed |\n| 4710 | Permission required |","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["machine_id","minutes"],"properties":{"machine_id":{"type":"integer","description":"Machine ID to assign usage to"},"minutes":{"type":"integer","description":"Number of minutes to assign"}}}}}}}}},"components":{"schemas":{"AssignUsageResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","description":"Response after assigning usage to a machine","properties":{"assigned_minutes":{"type":"integer","description":"Number of minutes assigned"},"machine_id":{"type":"integer","description":"Machine ID that received the usage"},"machine_type":{"type":"string","description":"Machine performance type"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error480Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error482Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````

## Retrieve Machine Usage

> Retrieve extra assigned usage from machine back to team balance.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### \*\*Body Parameters\*\*\
> \
> \| Parameter | Type | Required | Description |\
> \| --- | --- | --- | --- |\
> \| \`machine\_id\`\\\* | Integer | Yes | Machine ID |\
> \| \`minutes\`\\\* | Integer | Yes | Number of minutes to retrieve. Cannot exceed available usage. |\
> \
> \### Request Body Example\
> \
> \`\`\` json\
> {\
>   "machine\_id": 717,\
>   "minutes": 60\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Response Fields\*\*\
> \
> \| Field | Type | Description |\
> \| --- | --- | --- |\
> \| \`retrieved\_minutes\` | Integer | Number of minutes retrieved |\
> \| \`machine\_id\` | Integer | Machine ID |\
> \| \`machine\_type\` | String | Machine type name |\
> \| \`client\_code\` | Integer | Response code (200 for success) |\
> \| \`message\` | String | Response message |\
> \| \`timestamp\` | String | Response timestamp (ISO 8601) |\
> \
> \### \*\*Success Response Example\*\*\
> \
> \`\`\` json\
> {\
>     "retrieved\_minutes": 1,\
>     "machine\_id": 717,\
>     "machine\_type": "Planet",\
>     "client\_code": 200,\
>     "message": "OK",\
>     "timestamp": "2026-02-04T13:51:41Z"\
> }\
> \
>  \`\`\`\
> \
> \### \*\*Error Responses\*\*\
> \
> \| Status | Description |\
> \| --- | --- |\
> \| 400 | Bad request (missing required parameters) |\
> \| 404 | Machine not found |\
> \| 480 | No usages left in machine |\
> \| 482 | Usage retrieval failed |\
> \| 4710 | Permission required |

````json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.12"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/usage/retrieve":{"post":{"summary":"Retrieve Machine Usage","responses":{"200":{"description":"Usage retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveUsageResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"480":{"description":"No usages left in machine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error480Response"}}}},"482":{"description":"Usage retrieval failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error482Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Usages"],"description":"Retrieve extra assigned usage from machine back to team balance.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### **Body Parameters**\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `machine_id`\\* | Integer | Yes | Machine ID |\n| `minutes`\\* | Integer | Yes | Number of minutes to retrieve. Cannot exceed available usage. |\n\n### Request Body Example\n\n``` json\n{\n  \"machine_id\": 717,\n  \"minutes\": 60\n}\n\n ```\n\n### **Response Fields**\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `retrieved_minutes` | Integer | Number of minutes retrieved |\n| `machine_id` | Integer | Machine ID |\n| `machine_type` | String | Machine type name |\n| `client_code` | Integer | Response code (200 for success) |\n| `message` | String | Response message |\n| `timestamp` | String | Response timestamp (ISO 8601) |\n\n### **Success Response Example**\n\n``` json\n{\n    \"retrieved_minutes\": 1,\n    \"machine_id\": 717,\n    \"machine_type\": \"Planet\",\n    \"client_code\": 200,\n    \"message\": \"OK\",\n    \"timestamp\": \"2026-02-04T13:51:41Z\"\n}\n\n ```\n\n### **Error Responses**\n\n| Status | Description |\n| --- | --- |\n| 400 | Bad request (missing required parameters) |\n| 404 | Machine not found |\n| 480 | No usages left in machine |\n| 482 | Usage retrieval failed |\n| 4710 | Permission required |","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["machine_id","minutes"],"properties":{"machine_id":{"type":"integer","description":"Machine ID to retrieve usage from"},"minutes":{"type":"integer","description":"Number of minutes to retrieve (cannot exceed available usage)"}}}}}}}}},"components":{"schemas":{"RetrieveUsageResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","description":"Response after retrieving usage from a machine","properties":{"retrieved_minutes":{"type":"integer","description":"Number of minutes retrieved"},"machine_id":{"type":"integer","description":"Machine ID from which usage was retrieved"},"machine_type":{"type":"string","description":"Machine performance type"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error480Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error482Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
````