Soracom Batch API
Batch processing — create batch groups, define jobs that invoke API operations across many SIMs or devices, and inspect tasks for status and results.
OpenAPI Specification
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