Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/soracom-query-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Soracom Query API
version: 20250903-043502
description: 'Operations tagged Query across 2 of this provider''s published API definitions: soracom-analysis-query-api-openapi.yml, soracom-platform-api-openapi.yml. Each path carries the servers of the definition it was published in.'
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
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
/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
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
/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
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
/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
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
/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
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
components:
schemas:
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-northeast-1
- eu-central-1
- us-west-2
- ap-southeast-2
type: string
type: object
ArcSessionStatus:
properties:
arcAllowedIPs:
description: Displays the WireGuard AllowedIPs received from the Arc server.
items:
type: string
type: array
arcClientPeerIpAddress:
description: IP address of the client.
type: string
arcClientPeerPublicKey:
type: string
arcServerEndpoint:
description: WireGuard protocol endpoints on the Arc server.
type: string
arcServerPeerPublicKey:
description: Server peer public key for the Arc server.
type: string
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
lastUpdatedAt:
format: int64
type: integer
placement:
$ref: '#/components/schemas/Placement'
vpgId:
description: The VPG ID. If the VPG was not used, this will not be output.
type: string
type: object
TagSet:
additionalProperties:
type: string
description: An object which always contains at least one property "name" with a string value. If you give a subscriber/SIM a name, the name will be returned as the value of the "name" property. If the subscriber/SIM does not have a name, an empty string "" is returned. In addition, if you create any custom tags for the subscriber/SIM, each custom tag will appear as additional properties in the object.
example:
tagName1: tagValue1
tagName2: tagValue2...
type: object
Device:
properties:
device_id:
type: string
endpoint:
type: string
firmwareVersion:
type: string
groupId:
type: string
ipAddress:
type: string
lastModifiedTime:
format: date-time
type: string
lastRegistrationUpdate:
format: date-time
type: string
manufacturer:
type: string
modelNumber:
type: string
objects:
type: object
online:
default: false
type: boolean
operatorId:
type: string
registrationId:
type: string
registrationLifeTime:
format: int64
type: integer
serialNumber:
type: string
tags:
additionalProperties:
type: string
type: object
type: object
ImeiLock:
description: IMEI lock configuration.
properties:
imei:
description: IMEI of the target device
type: string
type: object
LastSeen:
properties:
rssi:
format: int32
type: integer
snr:
format: int32
type: integer
time:
format: date-time
type: string
type: object
Map:
additionalProperties:
type: string
type: object
LocationRegistrationStatusForNetwork:
properties:
lastModifiedTime:
description: Timestamp of the last successful network registration (Unix time in milliseconds)
format: int64
type: integer
vplmn:
description: PLMN ID of the visited network.
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
Capabilities:
properties:
data:
description: 'Data communication support.
- `true`: with data.
- `false`: without data.
'
type: boolean
sms:
description: 'SMS support.
- `true`: with SMS.
- `false`: without SMS.
'
type: boolean
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
SigfoxDevice:
properties:
device_id:
type: string
groupId:
type: string
lastModifiedTime:
format: date-time
type: string
lastSeen:
$ref: '#/components/schemas/LastSeen'
operatorId:
type: string
status:
enum:
- active
- ready
- terminated
- instock
type: string
tags:
additionalProperties:
type: string
type: object
terminationEnabled:
default: false
type: boolean
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 millisecond
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/soracom/refs/heads/main/openapi/soracom-query-api-openapi.yml