openapi: 3.0.0
info:
title: Soracom Analysis and 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
paths:
/analysis/queries:
post:
description: Executes a SQL query asynchronously. You can check the status of a SQL query execution with the [Analysis:getAnalysisQueries
API](#/Analysis/getAnalysisQueries).
operationId: startAnalysisQueries
requestBody:
content:
application/json:
example:
from: 1743465600
sql: SELECT * FROM SIM_SESSION_EVENTS LIMIT 10
to: 1743552000
schema:
$ref: '#/components/schemas/StartAnalysisQueriesRequest'
description: A SQL query execution request.
required: true
responses:
'200':
content:
application/json:
example:
queryId: ffa91d0c371d45c4bf53d55ab5c14955
schema:
$ref: '#/components/schemas/StartAnalysisQueriesResponse'
description: A new SQL query execution has started.
security:
- api_key: []
api_token: []
summary: Execute a new SQL query asynchronously
tags:
- Analysis
x-soracom-cli:
- analysis queries start
/analysis/queries/{query_id}:
get:
description: Retrieve the execution status of a SQL query.
operationId: getAnalysisQueries
parameters:
- description: SQL query ID.
in: path
name: query_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
columnInfo:
- databaseType: FIXED
name: ICCID
type: string
- databaseType: TEXT
name: IMEI
type: string
- databaseType: NUMBER
name: IMSI
type: number
fileSize: 12345678
rowCount: 12345
status: COMPLETED
url: https://soracom-analysis-export.s3.amazonaws.com/ffa91d0c-371d-45c4-bf53-d55ab5c14955.csv.gz
schema:
$ref: '#/components/schemas/GetAnalysisQueriesResponse'
description: The execution status, results, and download URL of the SQL query.
security:
- api_key: []
api_token: []
summary: Retrieve the execution status of a SQL query
tags:
- Analysis
x-soracom-cli:
- analysis queries get
/analysis/schemas:
get:
description: "Retrieves the available schemas and their column information within the database. You can use this information\
\ as a reference when converting data types of data retrieved with the [Analysis:startAnalysisQueries API](#/Analysis/startAnalysisQueries).\n\
Example: If the column `type` is `string` as shown below, it can be treated as a string.\n```json\n{\n \"name\":\
\ \"SIM_SESSION_EVENTS\",\n \"columnInfo\": [\n {\n \"name\": \"APN\",\n \"type\": \"string\"\
,\n \"databaseType\": \"TEXT\",\n \"description\": \"Access Point Name indicating the network gateway\
\ for the SIM session.\"\n }\n ]\n}\n```\n"
operationId: getAnalysisSchemas
responses:
'200':
content:
application/json:
example:
- columnInfo:
- databaseType: TEXT
description: Access Point Name indicating the network gateway for the SIM session.
name: APN
type: string
- databaseType: TEXT
description: The primary DNS server IP address used during the SIM session.
name: DNS0
type: string
- databaseType: TEXT
description: The secondary DNS server IP address used during the SIM session.
name: DNS1
type: string
- databaseType: TEXT
description: Describes the type of event associated with the SIM session, such as Created, Deleted, or Updated.
name: EVENT
type: string
- databaseType: TEXT
description: Home Public Land Mobile Network code that identifies the home network operator.
name: HPLMN
type: string
- databaseType: TEXT
description: The Integrated Circuit Card Identifier, a unique number assigned to the SIM card.
name: ICCID
type: string
name: SIM_SESSION_EVENTS
schema:
$ref: '#/components/schemas/GetAnalysisSchemasResponse'
description: A list of available database schemas and their column information.
security:
- api_key: []
api_token: []
summary: Retrieve available database schemas
tags:
- Analysis
x-soracom-cli:
- analysis schemas
/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
/resource_summaries/{resource_summary_type}:
get:
description: Obtain a resource summary information identified by resource_summary_type.
operationId: getResourceSummary
parameters:
- description: 'The type of the resource summary.
- `simsPerStatus`: The number of IoT SIMs per status.
'
in: path
name: resource_summary_type
required: true
schema:
enum:
- simsPerStatus
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceSummary'
description: The resource summary was found.
'404':
description: No such resource summary.
security:
- api_key: []
api_token: []
summary: Get the resource summary identified by resource_summary_type
tags:
- ResourceSummary
x-soracom-cli:
- resource-summaries get
tags:
- description: '[Soracom Query](/en/docs/query/)'
name: Analysis
- description: Search SIMs, Soracom Inventory devices, and Sigfox devices
name: Query
components:
schemas:
TrafficVolumeRanking:
properties:
imsi:
type: string
trafficVolume:
format: int64
type: integer
type: object
ImeiLock:
description: IMEI lock configuration.
properties:
imei:
description: IMEI of the target device
type: string
type: object
StartAnalysisQueriesResponse:
properties:
queryId:
description: SQL query ID.
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
SessionStatus:
description: Information about the current session.
properties:
cell:
$ref: '#/components/schemas/Cell'
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
lastUpdatedAt:
format: int64
type: integer
location:
type: object
online:
description: 'Session status.
- `true`: online
- `false`: offline
'
type: boolean
placement:
$ref: '#/components/schemas/Placement'
sessionId:
description: The session ID.
type: string
subscription:
description: The subscription.
type:
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/soracom/refs/heads/main/openapi/soracom-analysis-query-api-openapi.yml