openapi: 3.0.0
info:
title: Soracom and Analysis Query API
description: Run SQL queries against Soracom Query, fetch query schemas, and search SIMs, Inventory devices, and Sigfox 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
tags:
- description: Search SIMs, Soracom Inventory devices, and Sigfox devices
name: Query
paths:
/query/devices:
get:
description: 'Search Soracom Inventory devices by query terms. It returns partial match results. When this API permission is allowed, it grants the authority to search and retrieve all Soracom Inventory devices that include their group information.
**Warning**: Use this API when the device ID of the target Inventory device is unknown, or when you want to retrieve a list of Inventory devices that match conditions. If you know the device ID, use the [Device:getDevice API](#/Device/getDevice).
'
operationId: searchDevices
parameters:
- description: Name to search.
explode: true
in: query
name: name
required: false
schema:
items:
type: string
type: array
- description: Group name to search.
explode: true
in: query
name: group
required: false
schema:
items:
type: string
type: array
- description: Group ID to search.
explode: true
in: query
name: group_id
required: false
schema:
items:
type: string
type: array
- description: Soracom Inventory device ID to search.
explode: true
in: query
name: deviceId
required: false
schema:
items:
type: string
type: array
- description: String of tag values to search.
explode: true
in: query
name: tag
required: false
schema:
items:
type: string
type: array
- description: IMSI of the device that was used on bootstrapping.
explode: true
in: query
name: imsi
required: false
schema:
items:
type: string
type: array
- description: IMEI of the device that was used on bootstrapping.
explode: true
in: query
name: imei
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to retrieve.
in: query
name: limit
required: false
schema:
default: 10
format: int32
maximum: 100
type: integer
- description: The Soracom Inventory device ID of the last Inventory device retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next Inventory device onward.
in: query
name: last_evaluated_key
required: false
schema:
type: string
- description: Type of the search ('AND searching' or 'OR searching').
in: query
name: search_type
required: false
schema:
default: and
enum:
- and
- or
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Device'
type: array
description: Returns result of searching.
'400':
description: Invalid search queries.
security:
- api_key: []
api_token: []
summary: Search Soracom Inventory devices by query
tags:
- Query
x-soracom-cli:
- query devices
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
/query/sigfox_devices:
get:
description: 'Search Sigfox devices by query terms. It returns partial match results. When this API permission is allowed, it grants the authority to search and retrieve all Sigfox devices that includes their group information.
**Warning**: Use this API when the device ID of the target Sigfox device is unknown, or when you want to retrieve a list of Sigfox devices that match conditions. If you know the device ID, use the [SigfoxDevice:getSigfoxDevice API](#/SigfoxDevice/getSigfoxDevice).
'
operationId: searchSigfoxDevices
parameters:
- description: Name to search.
explode: true
in: query
name: name
required: false
schema:
items:
type: string
type: array
- description: Group name to search.
explode: true
in: query
name: group
required: false
schema:
items:
type: string
type: array
- description: Group ID to search.
explode: true
in: query
name: group_id
required: false
schema:
items:
type: string
type: array
- description: Sigfox device ID to search.
explode: true
in: query
name: deviceId
required: false
schema:
items:
type: string
type: array
- description: String of tag values to search.
explode: true
in: query
name: tag
required: false
schema:
items:
type: string
type: array
- description: Status of Sigfox devices.
in: query
name: status
required: false
schema:
default: and
enum:
- active
- inactive
- suspended
- terminated
- shipped
- ready
- inStock
- banned
- standby
type: string
- description: Registration status of Sigfox devices.
in: query
name: registration
required: false
schema:
default: and
enum:
- notStarted
- pending
- success
- failed
type: string
- description: The maximum number of items to retrieve.
in: query
name: limit
required: false
schema:
default: 10
format: int32
maximum: 100
type: integer
- description: The Sigfox device ID of the last Sigfox device retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next Sigfox device onward.
in: query
name: last_evaluated_key
required: false
schema:
type: string
- description: Type of the search ('AND searching' or 'OR searching').
in: query
name: search_type
required: false
schema:
default: and
enum:
- and
- or
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/SigfoxDevice'
type: array
description: Returns result of searching.
'400':
description: Invalid search queries.
security:
- api_key: []
api_token: []
summary: Search Sigfox devices by query
tags:
- Query
x-soracom-cli:
- query sigfox-devices
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
/query/sims:
get:
description: "Searches for SIMs using specified query parameters.\n\n- Supports partial matching.\n- Case-insensitive.\n- Multiple search values can be specified for the following parameters by separating each value with a comma `,` (or `%2C` when URL-encoded). Note that the literal character `,` itself cannot be used as part of a search value.\n - `name`\n - `group`\n - `sim_id`\n - `imsi`\n - `msisdn`\n - `iccid`\n - `serial_number`\n - `tag`\n - `status`\n - `subscription`\n - `module_type`\n- Each search value must be at least 2 characters long. When using a comma `,` to specify multiple search values, each value must also be at least 2 characters long (e.g., `ab,c` is invalid because `c` is only 1 character long).\n- When multiple query parameters are specified, the search type (AND search or OR search) can be specified using `search_type`.\n\n**Warning**: When this API permission is allowed, it grants the authority to search and retrieve all SIMs that include their group information.\n\n**Warning**: Use this API when the SIM ID of the target IoT SIM is unknown, or when you want to retrieve a list of SIMs that match certain conditions. If you know the SIM ID, please use the [Sim:getSim API](#/Sim/getSim) instead.\n"
operationId: searchSims
parameters:
- description: Name to search.
examples:
0_no_filter:
summary: No filter
value: []
1_filter_example:
summary: Search for IoT SIMs with specific name
value:
- example-sim
explode: true
in: query
name: name
required: false
schema:
items:
type: string
type: array
- description: Name of the [group](/en/docs/groups/) to which the IoT SIM belongs.
examples:
0_no_filter:
summary: No filter
value: []
1_filter_example:
summary: Search for IoT SIMs in specific group
value:
- example-group
explode: true
in: query
name: group
required: false
schema:
items:
type: string
type: array
- description: Search for IoT SIMs whose group ID matches the specified value.
explode: true
in: query
name: group_id
required: false
schema:
items:
type: string
type: array
- description: Identifier of the SIM to search.
explode: true
in: query
name: sim_id
required: false
schema:
items:
type: string
type: array
- description: IMSI to search.
explode: true
in: query
name: imsi
required: false
schema:
items:
type: string
type: array
- description: MSISDN to search.
explode: true
in: query
name: msisdn
required: false
schema:
items:
type: string
type: array
- description: ICCID to search. An identifier used to identify a SIM card or virtual IoT SIM (Virtual SIM/Subscriber).
explode: true
in: query
name: iccid
required: false
schema:
items:
type: string
type: array
- description: Serial number to search. This is set only for IoT SIMs for specific regions.
explode: true
in: query
name: serial_number
required: false
schema:
items:
type: string
type: array
- description: String of tag values to search. For more information, please refer to [Using Tags with Soracom Air](/docs/air/tags).
explode: true
in: query
name: tag
required: false
schema:
items:
type: string
type: array
- description: Bundles type to search.
explode: true
in: query
name: bundles
required: false
schema:
items:
type: string
type: array
- description: 'Status of the IoT SIM to search.
- `ready`
- `active`
- `inactive`
- `standby`
- `suspended`
- `terminated`
- `shipped`
'
explode: true
in: query
name: status
required: false
schema:
items:
type: string
type: array
- description: 'Status of the session to search. Specify one of the following:
- `NA`: Any.
- `ONLINE`: Online.
- `OFFLINE`: Offline.
'
in: query
name: session_status
required: false
schema:
default: NA
enum:
- NA
- ONLINE
- OFFLINE
format: string
type: string
- description: "Subscription to search. Use exact match for the search. If specifying multiple subscriptions, please set `search_type` to `OR`.\n\n- For Japan coverage, specify one of the following:\n - `plan-D`: plan-D (without bundle), plan-D (D-300MB).\n - `plan-K2`: plan-K2 (K2-300MB).\n - `plan-DU`\n - `plan-KM1`\n - `plan-K`\n - `planArc01`: Virtual SIM/Subscriber.\n- For global coverage, specify one of the following:\n - `plan01s`\n - `plan01s-low_data_volume`: plan01s - Low Data Volume.\n - `planX3`: planX3 (X3-5MB), planX3.\n - `planP1`\n - `plan-US`\n - `plan-US-max`\n - `planX1`\n - `planX2`\n - `planX3-EU`\n - `plan-US-NA`\n - `planArc01`: Virtual SIM/Subscriber.\n"
explode: true
in: query
name: subscription
required: false
schema:
items:
type: string
type: array
- description: 'The form factor of the physical SIM to search.
- `mini`: standard (2FF) size.
- `micro`: micro (3FF) size.
- `nano`: nano (4FF) size.
- `trio`: 3 in 1 (can be cut into 2FF/3FF/4FF depending on how you cut it).
- `embedded`: Embedded (MFF2).
- `virtual`: Virtual SIM/Subscriber.
- `integrated`: Embedded (iSIM).
- `profilePackage`: Profile Package (eSIM profile).
'
explode: true
in: query
name: module_type
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to retrieve.
in: query
name: limit
required: false
schema:
default: 10
format: int32
maximum: 100
type: integer
- description: The SIM ID of the last SIM retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next SIM onward.
in: query
name: last_evaluated_key
required: false
schema:
type: string
- description: 'The type of search condition.
- AND: SIMs which match all of the search parameters will be returned (default).
- OR: SIMs which match any of the search parameters will be returned.
If the value of a search parameter contains a comma `,` (or `%2C` when URL-encoded), the value will be split at each comma and treated as multiple search values, each of which will be evaluated based on the specified AND or OR condition.
'
in: query
name: search_type
required: false
schema:
default: and
enum:
- and
- or
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Sim'
type: array
description: Returns result of searching.
'400':
description: Invalid search queries.
security:
- api_key: []
api_token: []
summary: Search SIMs by query terms
tags:
- Query
x-soracom-cli:
- query sims
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
/query/subscribers:
get:
deprecated: true
description: '(DEPRECATED: please consider to use `/query/sims` API instead ) Search subscribers by query terms. It returns partial match results. When this API permission is allowed, it grants the authority to search and retrieve all SIMs that includes their group information.'
operationId: searchSubscribers
parameters:
- description: Name to search.
explode: true
in: query
name: name
required: false
schema:
items:
type: string
type: array
- description: Group name to search.
explode: true
in: query
name: group
required: false
schema:
items:
type: string
type: array
- description: IMSI to search.
explode: true
in: query
name: imsi
required: false
schema:
items:
type: string
type: array
- description: MSISDN to search.
explode: true
in: query
name: msisdn
required: false
schema:
items:
type: string
type: array
- description: ICCID to search.
explode: true
in: query
name: iccid
required: false
schema:
items:
type: string
type: array
- description: Serial number to search.
explode: true
in: query
name: serial_number
required: false
schema:
items:
type: string
type: array
- description: String of tag values to search.
explode: true
in: query
name: tag
required: false
schema:
items:
type: string
type: array
- description: "Subscription to search. Use exact match for the search. If specifying multiple subscriptions, please set `search_type` to `OR`.\n\n- For Japan coverage, specify one of the following:\n - `plan-D`: plan-D (without bundle), plan-D (D-300MB).\n - `plan-K2`: plan-K2 (K2-300MB).\n - `plan-DU`\n - `plan-KM1`\n - `plan-K`\n - `planArc01`: Virtual SIM/Subscriber.\n- For global coverage, specify one of the following:\n - `plan01s`\n - `plan01s-low_data_volume`: plan01s - Low Data Volume.\n - `planX3`: planX3 (X3-5MB), planX3.\n - `planP1`\n - `plan-US`\n - `plan-US-max`\n - `planX1`\n - `planX2`\n - `planX3-EU`\n - `plan-US-NA`\n - `planArc01`: Virtual SIM/Subscriber.\n"
explode: true
in: query
name: subscription
required: false
schema:
items:
type: string
type: array
- description: Module type (e.g. `mini`, `virtual`) to search.
explode: true
in: query
name: module_type
required: false
schema:
items:
type: string
type: array
- description: The maximum number of item to retrieve.
in: query
name: limit
required: false
schema:
default: 10
format: int32
maximum: 100
type: integer
- description: The IMSI of the last subscriber retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next subscriber onward.
in: query
name: last_evaluated_key
required: false
schema:
type: string
- description: Type of the search ('AND searching' or 'OR searching').
in: query
name: search_type
required: false
schema:
default: and
enum:
- and
- or
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Subscriber'
type: array
description: Returns result of searching.
'400':
description: Invalid search queries.
security:
- api_key: []
api_token: []
summary: (DEPRECATED) Search subscribers by query terms
tags:
- Query
x-soracom-alternative-cli: query sims
x-soracom-cli:
- query subscribers
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
/query/subscribers/traffic_volume/ranking:
get:
description: Search traffic volume ranking of subscribers.
operationId: searchSubscriberTrafficVolumeRanking
parameters:
- description: The beginning point of searching range (UNIX time in milliseconds).
in: query
name: from
required: true
schema:
format: int64
type: integer
- description: The end point of searching range (UNIX time in milliseconds).
in: query
name: to
required: true
schema:
format: int64
type: integer
- description: The maximum number of item to retrieve.
in: query
name: limit
required: false
schema:
default: 10
format: int32
maximum: 500
type: integer
- description: The order of ranking.
in: query
name: order
required: false
schema:
default: desc
enum:
- asc
- desc
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/TrafficVolumeRanking'
type: array
description: OK.
security:
- api_key: []
api_token: []
summary: Search traffic volume ranking of subscribers
tags:
- Query
x-soracom-cli:
- query subscribers traffic-volume-ranking
- query traffic-ranking
components:
schemas:
Map:
additionalProperties:
type: string
type: object
SimProfile:
properties:
arcClientPeerPrivateKey:
description: 'The client''s PrivateKey (client peer private key) for connecting with WireGuard.
- PrivateKey (client peer private key) cannot be redisplayed. If you have lost your private key, generate a new key and update the device credentials.
- Never disclose connection information to outside parties.
'
type: string
arcClientPeerPublicKey:
type: string
iccid:
type: string
otaSupported:
type: boolean
primaryImsi:
type: string
subscribers:
additionalProperties:
$ref: '#/components/schemas/SimplifiedSubscriber'
type: object
type: object
LastSeen:
properties:
rssi:
format: int32
type: integer
snr:
format: int32
type: integer
time:
format: date-time
type: string
type: object
LocationRegistrationStatus:
properties:
cs:
$ref: '#/components/schemas/LocationRegistrationStatusForNetwork'
description: Information on location registration to the CS network
eps:
$ref: '#/components/schemas/LocationRegistrationStatusForNetwork'
description: Information on location registration to the EPS network
ps:
$ref: '#/components/schemas/LocationRegistrationStatusForNetwork'
description: Information on location registration to the PS network
type: object
SimplifiedSubscriber:
properties:
bundles:
items:
type: string
type: array
capabilities:
$ref: '#/components/schemas/Capabilities'
imsi:
description: IMSI
type: string
msisdn:
type: string
status:
description: 'Status of the IoT SIM (primary subscription of the IoT SIM) or status of the additional subscription.
For primary subscriptions, it refers to the status of the IoT SIM.
- `ready`
- `active`
- `inactive`
- `standby`
- `suspended`
- `terminated`
For additional subscriptions, it refers to the status of the additional subscription.
- `shipped`: OTA is ready or in progress (first half).
- `delivered`: OTA is in progress (second half).
- `ready`: OTA is complete.
- `active`: A connection via the additional subscription has been confirmed. This does not refer to the status of the IoT SIM.
- `terminated`
The status of the virtual SIM/subscriber is either `active` or `terminated`.
'
enum:
- shipped
- delivered
- ready
- active
- terminated
type: string
subscription:
type: string
type: object
PreviousSessionStatus:
description: Information about the previous session.
properties:
cell:
$ref: '#/components/schemas/Cell'
createdTime:
description: The time when the previous session was created.
format: int64
type: integer
deletedTime:
description: The time when the previous session was deleted.
format: int64
type: integer
dnsServers:
description: Array of IP address of the DNS servers.
items:
type: string
type: array
gatewayPrivateIpAddress:
description: The private IP address of the VPG. In the case of VPG Type-F, the source IP address of the closed network communication from the IoT SIM to the customer's system is NAT-ed to this IP address.
type: string
gatewayPublicIpAddress:
description: The fixed global IP address when using the VPG [Fixed Global IP Address Option](/en/docs/vpg/fixed-global-ip/).
type: string
imei:
description: The IMEI of the device using the IoT SIM. If using a virtual SIM/subscriber, this will be `null`.
type: string
imsi:
description: The IMSI of the IoT SIM.
type: string
sessionId:
description: The session ID.
type: string
subscription:
type: string
ueIpAddress:
description: The IP address of the device.
type: string
vpgId:
description: The VPG ID. If the VPG was not used, this will not be output.
type: string
type: object
Sim:
properties:
activeProfileId:
type: string
arcSessionStatus:
$ref: '#/components/schemas/ArcSessionStatus'
capabilities:
$ref: '#/components/schemas/Capabilities'
createdTime:
description: UNIX time (in milliseconds) that the IoT SIM (primary subscription to the IoT SIM) was created.
format: int64
type: integer
expiryAction:
description: 'Action when expiration date expires. Please refer to [Soracom Air Expiration Function](/en/docs/air/expiration/) for more detail.
- `doNothing` : do nothing
- `deleteSession` : delete session of the SIM if any
- `deactivate` : change the SIM status to Inactive
- `suspend` : change the SIM status to Suspended
- `terminate` : forcibly end any existing connections, and terminate the SIM
- `null`: No expiration date set.
'
enum:
- doNothing
- deleteSession
- deactivate
- suspend
- terminate
- (null value)
type: string
expiryTime:
description: IoT SIM expiration date (UNIX time in milliseconds).
format: int64
type: integer
groupId:
description: The SIM group ID where the SIM belongs to.
type: string
imeiLock:
$ref: '#/components/schemas/ImeiLock'
lastModifiedTime:
description: UNIX time (in milliseconds) that the information in the IoT SIM (primary subscription to the IoT SIM) was changed
format: int64
type: integer
lastPortMappingCreatedTime:
description: UNIX time in milliseconds that Napter was used with the SIM. If Napter has never been used with the SIM, null is returned.
format: int64
type: integer
localInfo:
$ref: '#/components/schemas/Map'
moduleType:
description: 'The form factor of the physical SIM.
- `mini`: standard (2FF) size.
- `micro`: micro (3FF) size.
- `nano`: nano (4FF) size.
- `trio`: 3 in 1 (can be cut into 2FF/3FF/4FF depending on how you cut it).
- `embedded`: Embedded (MFF2).
- `virtual`: Virtual SIM/Subscriber.
- `integrated`: Embedded (iSIM).
- `profilePackage`: Profile Package (eSIM profile).
'
enum:
- mini
- micro
- nano
- trio
- embedded
- virtual
- integrated
- profilePackage
type: string
operatorId:
description: The ID of the operator who owns this SIM.
type: string
otaSerialNumber:
type: string
pcapEndTime:
format: int64
type: integer
pcapStartTime:
format: int64
type: integer
previousSession:
$ref: '#/components/schemas/PreviousSessionStatus'
profiles:
additionalProperties:
$ref: '#/components/schemas/SimProfile'
type: object
renewalFeeStatusSetTime:
description: UNIX time (in milliseconds) that the IoT SIM status is either "ready", "standby", or "suspended".
format: int64
type: integer
serialNumber:
description: The serial number of the SIM. Virtual SIM/Subscriber does not have a serial number.
type: string
sessionStatus:
$ref: '#/components/schemas/SessionStatus'
simId:
description: The SIM ID of the SIM.
type: string
speedClass:
description: The speed class of the SIM.
type: string
status:
description: 'Status of the IoT SIM (primary subscription of the IoT SIM). The status of the virtual SIM/subscriber added to the IoT SIM is either `active` or `terminated`.
- `ready`
- `active`
- `inactive`
- `standby`
- `suspended`
- `terminated`
'
enum:
- ready
- active
- inactive
- standby
- suspended
- terminated
type: string
tags:
$ref: '#/components/schemas/TagSet'
terminationEnabled:
description: 'Value indicating whether the IoT SIM can be terminated (termination protection setting).
- `true`: Can be terminated (termination protection OFF)
- `false`: Cannot be terminated (termination protection ON)
'
type: boolean
testmodeExhaustedTime:
description: UNIX time (in milliseconds) when the SIM exceeded the testing usage limit.
format: int64
type: integer
type:
description: 'IoT SIM Type
- `euicc`: Chip type (eSIM)
- `uicc`: Card type
- `virtual`: Virtual SIM/Subscriber
'
enum:
- euicc
- uicc
- virtual
type: string
type: object
Placement:
properties:
infrastructureProvider:
enum:
- aws
type: string
region:
description: 'If `infrastructureProvider` is `aws`, it indicates the rendezvous point.
- `ap-northeast-1`: Tokyo (Japan). The default for Japan coverage.
- `eu-central-1`: Frankfurt (Germany). The default for Global coverage.
- `us-west-2`: Oregon (USA).
- `ap-southeast-2`: Sydney (Australia).
'
enum:
- ap-
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/soracom/refs/heads/main/openapi/soracom-query-api-openapi.yml