openapi: 3.0.0 info: title: Soracom Batch API description: Create and run batch jobs that apply API calls across multiple SIMs or devices. version: 20250903-043502 servers: - description: Japan coverage production API endpoint url: https://api.soracom.io/v1 - description: Global coverage production API endpoint url: https://g.api.soracom.io/v1 paths: /batch_groups: get: description: Returns a list of batch groups. operationId: listBatchGroups parameters: - description: Maximum number of batch groups to retrieve. The number of batch groups returned may be less than the specified value. example: 10 in: query name: limit required: false schema: format: int32 type: integer - description: The value of the `x-soracom-next-key` header returned in the response to the last request. Specify this to retrieve the next page of batch groups. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BatchGroupResponse' type: array description: A list of batch groups was retrieved successfully. security: - api_key: [] api_token: [] summary: List batch groups. tags: - Batch x-soracom-cli: - batch-groups list x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key post: description: 'Create a new batch group for organizing and managing batch jobs. To create a batch job, use the [Batch:createBatchJob](#/Batch/createBatchJob) instead. ' operationId: createBatchGroup requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBatchGroupRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchGroupResponse' description: The batch group has been created. security: - api_key: [] api_token: [] summary: Create batch group. tags: - Batch x-soracom-cli: - batch-groups create /batch_groups/{batch_group_id}: delete: description: 'Delete the specified batch group. Batch groups can only be deleted if there are no running batch jobs in the group. ' operationId: deleteBatchGroup parameters: - description: Batch group ID. in: path name: batch_group_id required: true schema: type: string responses: '204': description: The batch group has been deleted. '400': description: The batch group cannot be deleted because there are running batch jobs. '404': description: Batch group not found. security: - api_key: [] api_token: [] summary: Delete batch group. tags: - Batch x-soracom-cli: - batch-groups delete get: description: 'Returns details of the specified batch group. ' operationId: getBatchGroup parameters: - description: Batch group ID. in: path name: batch_group_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchGroupResponse' description: The batch group was found. '404': description: Batch group not found. security: - api_key: [] api_token: [] summary: Get batch group. tags: - Batch x-soracom-cli: - batch-groups get put: description: 'Updates the name or description of the specified batch group. ' operationId: updateBatchGroup parameters: - description: Batch group ID. in: path name: batch_group_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateBatchGroupRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchGroupResponse' description: The batch group was updated. '404': description: Batch group not found. security: - api_key: [] api_token: [] summary: Update batch group. tags: - Batch x-soracom-cli: - batch-groups update /batch_groups/{batch_group_id}/jobs: get: description: Returns a list of batch jobs in the specified batch group. operationId: listBatchJobs parameters: - description: Batch group ID. in: path name: batch_group_id required: true schema: type: string - description: Maximum number of batch jobs to retrieve. The number of batch jobs returned may be less than the specified value. example: 10 in: query name: limit required: false schema: format: int32 type: integer - description: The value of the `x-soracom-next-key` header returned in the response to the last request. Specify this to retrieve the next page of batch jobs. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BatchJobResponse' type: array description: A list of batch jobs was retrieved successfully. '404': description: Batch group not found. security: - api_key: [] api_token: [] summary: List batch jobs. tags: - Batch x-soracom-cli: - batch-groups jobs list x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key post: description: 'Create a new batch job and run it. A batch job consists of multiple tasks, each representing an API operation to be performed. Tasks are executed using the permissions of the user that created the batch job API. Batch job information is retained for 32 days. **System Limits:** - Each batch job is limited to a single API action. Mixing different APIs in the same job is not supported. - Each batch job is limited to a maximum of 10,000 tasks. - Only one batch job per API action can be created and processed at a time. - Batch jobs may be delayed or restricted if system load is high. If this occurs, please wait and try again later. ' operationId: createBatchJob parameters: - description: Batch group ID. in: path name: batch_group_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBatchJobRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchJobResponse' description: The batch job has been created and execution has started. '400': description: 'Bad request. This error can occur in the following cases: - Attempting to mix different APIs in a single batch job - Already running a batch job with the same API for this operator ' '404': description: Batch group not found. '429': description: Batch job execution is restricted due to high system load. security: - api_key: [] api_token: [] summary: Create and run batch job. tags: - Batch x-soracom-cli: - batch-groups jobs create /batch_groups/{batch_group_id}/jobs/{job_id}: get: description: 'Returns information about the specified batch job. ' operationId: getBatchJob parameters: - description: Batch group ID. in: path name: batch_group_id required: true schema: type: string - description: Batch job ID. in: path name: job_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchJobResponse' description: The batch job was found. '404': description: Batch job not found. security: - api_key: [] api_token: [] summary: Get batch job. tags: - Batch x-soracom-cli: - batch-groups jobs get /batch_groups/{batch_group_id}/jobs/{job_id}/tasks: get: description: 'Returns a list of tasks in the specified batch job. Each task represents an individual API operation executed as part of the batch job. ' operationId: listTasksOfBatchJob parameters: - description: Batch group ID. in: path name: batch_group_id required: true schema: type: string - description: Batch job ID. in: path name: job_id required: true schema: type: string - description: Maximum number of tasks to retrieve. The number of tasks returned may be less than the specified value. example: 10 in: query name: limit required: false schema: format: int32 type: integer - description: Filter by task status. in: query name: status required: false schema: enum: - pending - success - error type: string - description: The value of the `x-soracom-next-key` header returned in the response to the last request. Specify this to retrieve the next page of tasks. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BatchTaskResponse' type: array description: A list of batch tasks was retrieved successfully. '404': description: Batch job not found. security: - api_key: [] api_token: [] summary: List tasks. tags: - Batch x-soracom-cli: - batch-groups jobs list-tasks x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key tags: - description: Batch processing name: Batch components: schemas: BatchTaskRequest: properties: request: $ref: '#/components/schemas/BatchTaskApiRequest' description: (Not shown because $ref is used at the same level in base/batch.yaml) required: - request type: object BatchJobResponse: properties: abortOnFailure: description: Whether to immediately abort upon encountering an error. type: boolean batchGroupId: description: Batch group ID. example: aaaa1111 type: string createdTime: description: Created time. example: 1704067200 format: int64 type: integer description: description: Description of the batch job. type: string errorMessage: description: Detailed information about the failed batch job. type: string finishedTime: description: Finished time. example: 1704240000 format: int64 type: integer jobId: description: Batch job ID. example: bbbb2222 type: string jobName: description: Batch job name. example: July 16th 2025 Set group type: string status: description: 'Status of the batch job. - `pending`: The job is preparing to execute. No tasks have been processed yet. - `running`: The job is executing tasks. - `completed`: The job has finished successfully. All tasks have been executed without any errors. - `failed`: The job has finished processing all tasks, but one or more tasks encountered errors during execution. - `aborted`: The job was stopped before all tasks could be processed. ' enum: - pending - running - completed - aborted - failed type: string summary: $ref: '#/components/schemas/BatchJobSummary' updatedTime: description: Updated time. example: 1704153600 format: int64 type: integer type: object UpdateBatchGroupRequest: properties: batchGroupName: description: Batch group name. maxLength: 100 type: string description: description: Description of the batch group. maxLength: 500 type: string type: object CreateBatchGroupRequest: properties: batchGroupName: description: Batch group name. example: Monthly SIM Tag Update maxLength: 100 type: string description: description: Description of the batch group. maxLength: 500 type: string required: - batchGroupName type: object BatchGroupResponse: properties: batchGroupId: description: Batch group ID. example: aaaa1111 type: string batchGroupName: description: Batch group name. example: Monthly SIM Tag Update type: string createdTime: description: Created time. example: 1704067200 format: int64 type: integer description: description: Description of the batch group. type: string updatedTime: description: Updated time. example: 1704153600 format: int64 type: integer type: object BatchTaskApiResponse: description: このタスクの API レスポンス。 properties: body: description: Body in the response. type: object statusCode: description: Status code in the response. example: 200 type: integer type: object CreateBatchJobRequest: properties: abortOnFailure: description: Whether to immediately abort upon encountering an error during batch job execution. example: false type: boolean description: description: Description of the batch job. maxLength: 500 type: string jobName: description: Batch job name. example: July 16th 2025 Set group maxLength: 100 type: string tasks: description: "List of tasks to be executed in the batch job.\n\nSupported Soracom APIs:\n\n- [Sim:activateSim API](#/Sim/activateSim)\n\ - [Sim:deactivateSim API](#/Sim/deactivateSim)\n- [Sim:setSimToStandby API](#/Sim/setSimToStandby)\n- [Sim:suspendSim\ \ API](#/Sim/suspendSim)\n- [Sim:setSimGroup API](#/Sim/setSimGroup)\n- [Sim:unsetSimGroup API](#/Sim/unsetSimGroup)\n\ - [Sim:putSimTags API](#/Sim/putSimTags)\n- [VirtualPrivateGateway:putVirtualPrivateGatewayIpAddressMapEntry API](#/VirtualPrivateGateway/putVirtualPrivateGatewayIpAddressMapEntry)\n\ \nSpecify the API request path, HTTP method, and body in the `request` field according to the Soracom API specification.\ \ For example, to call the Sim:activateSim API, specify as follows:\n\n```json\n{\n \"request\": {\n \"path\"\ : \"/v1/sims/8981100001234567890/activate\",\n \"method\": \"POST\",\n \"body\": {\n \"sim_id\": \"\ 8981100001234567890\"\n }\n }\n}\n```\n" items: $ref: '#/components/schemas/BatchTaskRequest' type: array required: - tasks type: object BatchTaskApiRequest: description: The API request of this task. properties: body: description: Body of the API request. example: groupId: 11111111-2222-3333-4444-555555555555 type: object method: description: HTTP method of the API request. enum: - POST - GET - PUT - DELETE example: POST type: string path: description: Path of the API request. example: /v1/sims/8981100001234567890/set_group type: string required: - path - method type: object BatchTaskResponse: properties: finishedTime: description: Finished time of the task. example: 1704067202 format: int64 type: integer request: $ref: '#/components/schemas/BatchTaskApiRequest' description: (Not shown because $ref is used at the same level in base/batch.yaml) response: $ref: '#/components/schemas/BatchTaskApiResponse' description: (Not shown because $ref is used at the same level in base/batch.yaml) startedTime: description: Started time of the task. example: 1704067201 format: int64 type: integer status: description: 'Status of the task. - `pending`: Task is waiting for execution. - `success`: Task succeeded. - `error`: Task failed. ' enum: - pending - success - error type: string taskId: description: Task ID. example: 1 format: int32 type: integer type: object BatchJobSummary: description: Number of tasks for each status. These numbers are periodically updated during the batch job execution. properties: error: description: Number of tasks that failed to execute. example: 0 format: int32 type: integer pending: description: Number of tasks waiting for execution. example: 5 format: int32 type: integer success: description: Number of tasks that have successfully executed. example: 95 format: int32 type: integer type: object securitySchemes: api_key: description: 'API key for authentication. Obtain this from the Soracom User Console or via the Auth API. Required in combination with an API token for all authenticated requests. ' in: header name: X-Soracom-API-Key type: apiKey api_token: description: 'API token for authentication. This token has an expiration time and must be refreshed periodically. Required in combination with an API key for all authenticated requests.' in: header name: X-Soracom-Token type: apiKey