# 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.6"},"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.6"},"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.6"},"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.6"},"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.6"},"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"}]}}}}
````


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.vagon.io/teams/reference/usages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.