> ## Documentation Index > Fetch the complete documentation index at: https://docs.hologram.io/llms.txt > Use this file to discover all available pages before exploring further. # List data plans > List all data plans. Returns all data plans matching the specified parameters. ## OpenAPI ````yaml /api/1/openapi.yaml get /plans openapi: 3.0.0 info: title: Hologram REST API v1 description: >- The Hologram HTTP API is a REST-style interface for managing Hologram devices, accounts, and cloud data. Using the Hologram REST API, you can activate SIMs, get your devices approximate location, send SMS to your devices, update a device's usage limit, and much more. ## Authentication Hologram supports **HTTP Basic authentication** using API keys. Simply set the username of the request to `apikey`. The password field is the API key itself. You can find your API key on the Hologram Dashboard under [Account Settings](https://dashboard.hologram.io/settings/api). Your API key gives you access to your personal account, as well as any organizations you are a member of. Make sure you don't store your API key in a publicly accessible place like GitHub. If you are a member of multiple organizations, many endpoints accept an `orgid` argument to filter for devices or other objects within a specific organization. You can find your `orgid` by following [this guide from our Help Center](https://support.hologram.io/hc/en-us/articles/360035421234-What-is-my-organization-ID-orgid). ### Header Example ``` curl --verbose GET \ 'https://dashboard.hologram.io/api/1/users/me' \ -u apikey:YOUR_API_KEY ``` You can also base64 encode "apikey:YOUR_API_KEY" and include it directly in the header. ``` curl --verbose GET \ 'https://dashboard.hologram.io/api/1/users/me' \ --header "Authorization: Basic BASE64(apikey:YOUR_API_KEY)" ``` ## Requests Request bodies can be provided in either JSON or form-urlencoded formats. Please note that the examples in this documentation will only display JSON bodies. ### **JSON body** ``` curl --verbose --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Basic BASE64(apikey:YOUR_API_KEY)" \ --data '{"deviceid": 56668, "body": "Hello device!"}' \ 'https://dashboard.hologram.io/api/1/sms/incoming' ``` ### **form-urlencoded body** ``` curl --verbose --request POST \ --header "Content-Type: application/x-form-urlencoded" \ --header "Authorization: Basic BASE64(apikey:YOUR_API_KEY)" \ --data 'deviceid=56668&body=Hello%20device!' \ 'https://dashboard.hologram.io/api/1/sms/incoming' ``` ## Responses All API responses are returned as JSON objects with the following fields: * `success` (boolean) - Indicates whether the request was successful. * `data` (object or array) - Contains the requested data or information about the operation that was performed. Only present when `success` is true. * `error` (string) - Information about why the request failed. Only present when `success` is false. Most GET responses will also include the following fields if a limit is included as part of the query string: * `limit` (number) - The query limit, some have this value built in and others often have a maximum value that the limit can be * `size` (number) - The number of values returned by the query * `continues` (boolean, optional) - This is only returned if there are more values than were returned * `links` (array) - Contains information related to the query performed * `path` (string) - The API endpoint path * `base` (string) - API base URL * `next` (string) - URL with query string to get the next results Note that all dates and times are returned in UTC. ## Rate Limiting In order to provide a good quality of service to all of our customers, we enforce a rate limit on all API requests. If you exceed the rate limit you will receive a HTTP 429 response with a JSON response body like this: ``` { "success":false, "error":"API rate limit exceeded" } ``` If you receive this response, you should refrain from making requests for 5-10 seconds and then retry the request. Hologram's REST API provides methods to perform many requests in bulk. For example, you can change the data plans of multiple SIMs at once using https://dashboard.hologram.io/api/1/links/cellular/changeplan. If there is request you would like to make in bulk but cannot, please reach out to [support@hologram.io](mailto:support@hologram.io) for assistance. version: '1' servers: - url: https://dashboard.hologram.io/api/1 description: Hologram REST API v1 security: [] tags: - name: Devices description: Devices - name: SIM Configuration description: SIM Configuration x-group: SIM Configuration - Conductor - name: Organizations description: Organizations - name: Personal account description: Personal account - name: Async Change Requests description: Async Change Requests paths: /plans: get: tags: - Organizations summary: List data plans description: |- List all data plans. Returns all data plans matching the specified parameters. operationId: getPlans parameters: - name: orgid in: query description: Filter results to this organization ID required: false schema: type: integer - name: id in: query description: Filter by a specific plan ID required: false schema: type: integer - name: ids in: query description: Comma-separated list of plan IDs to filter by required: false schema: type: string - name: name in: query description: Filter results to plans whose name contains this string required: false schema: type: string - name: carrierid in: query description: Filter results to plans available on this carrier ID required: false schema: type: integer - name: display_category in: query description: Filter results to plans in this display category required: false schema: type: string - name: startafter in: query description: >- Return results after the record with this ID (cursor-based pagination) required: false schema: type: integer - name: include_rate_card_range in: query description: >- When true, each plan response will include variable_rates_range metadata sourced from the rate card API required: false schema: type: boolean - name: rate_card_effective_date in: query description: Override the effective date used when fetching plan rate card data required: false schema: type: string - name: limit in: query description: Maximum number of results to return (max 1000) required: false schema: type: integer maximum: 1000 example: 25 - name: cellular_coverage_region_id in: query description: Filter results to plans assigned to this cellular coverage region ID required: false schema: type: integer - name: network in: query description: >- Filter results to plans available on this carrier ID (alias for carrierid) required: false schema: type: integer - name: includezdr in: query description: >- When true, include zero data rate fields (zero_data_rate_flag, zero_data_rate) in each pricing tier required: false schema: type: boolean - name: includepid in: query description: >- When true, include the pricing entry ID (tier_pricing_id) in each pricing tier required: false schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListPlansResponse' '401': description: Unauthorized security: - apiKeyAuth: [] components: schemas: ListPlansResponse: properties: success: $ref: '#/components/schemas/SuccessProperty' limit: type: integer size: type: integer continues: type: boolean lastid: description: ID of the last record returned, for cursor-based pagination type: integer links: $ref: '#/components/schemas/PaginationLinks' data: type: array items: $ref: '#/components/schemas/DataPlanDetailsObject' type: object SuccessProperty: description: Indicates whether the request was successful. type: boolean example: true PaginationLinks: properties: path: description: The API endpoint path type: string base: description: The API base URL type: string next: description: URL to retrieve the next page of results type: string type: object DataPlanDetailsObject: properties: id: description: Unique plan ID type: integer name: description: Plan name type: string description: description: Plan description type: string data: description: Included data in bytes type: integer billingperiod: description: Billing period in days type: integer recurring: description: 1 if the plan auto-renews type: integer enum: - 0 - 1 enabled: description: 1 if the plan is currently available type: integer enum: - 0 - 1 developerplan: description: 1 if this is a developer plan type: integer enum: - 0 - 1 groupid: description: Plan group ID type: integer partnerid: description: Partner this plan belongs to type: integer display_category: description: Display category for this plan type: string nullable: true cellular_coverage_region_id: description: Cellular coverage region ID type: integer nullable: true use_variable_rates: description: Whether this plan uses variable rates type: boolean is_dynamic_pool: description: Whether this plan uses a dynamic pool type: boolean cellular_coverage_region: oneOf: - $ref: '#/components/schemas/PlanCoverageRegion' nullable: true description: >- Coverage region details, present when cellular_coverage_region_id is set tiers: $ref: '#/components/schemas/DataPlanTiersMap' current_tier: description: Current pricing tier for the requesting organization type: string nullable: true zones: oneOf: - $ref: '#/components/schemas/DataPlanZonesMap' nullable: true description: Top-level zone view for the current_tier (legacy compatibility) amountglobal: description: >- Legacy flattened amount for the global zone (key name matches zone name casing) type: string nullable: true smsglobal: description: >- Legacy flattened SMS amount for the global zone (key name matches zone name casing) type: string nullable: true overageglobal: description: >- Legacy flattened overage amount for the global zone (key name matches zone name casing) type: string nullable: true variable_rates_range: oneOf: - $ref: '#/components/schemas/PlanVariableRatesRange' nullable: true description: Variable rate range when include_rate_card_range is requested profiles: description: Carrier profiles (present on single-plan responses only) type: array items: $ref: '#/components/schemas/DataPlanProfile' nullable: true type: object PlanCoverageRegion: properties: id: description: Region ID type: integer display_name: description: Region display name type: string description: description: Region description type: string type: object DataPlanTiersMap: type: object additionalProperties: $ref: '#/components/schemas/DataPlanTierObject' DataPlanZonesMap: type: object additionalProperties: $ref: '#/components/schemas/DataPlanZoneObject' PlanVariableRatesRange: properties: min: description: Minimum price per megabyte type: number nullable: true max: description: Maximum price per megabyte type: number nullable: true type: object DataPlanProfile: properties: carrierId: description: Carrier ID type: integer name: description: Profile name type: string offerId: description: Carrier offer ID type: integer type: object DataPlanTierObject: properties: devicecount: description: Device count for this tier type: integer zones: $ref: '#/components/schemas/DataPlanZonesMap' type: object DataPlanZoneObject: properties: amount: description: Per-MB amount for this zone (stringified decimal) type: string sms: description: Per-SMS amount for this zone (stringified decimal) type: string overage: description: Overage amount for this zone (stringified decimal) type: string carriers: $ref: '#/components/schemas/DataPlanZoneCarrierMap' type: object DataPlanZoneCarrierMap: type: object additionalProperties: $ref: '#/components/schemas/DataPlanZoneCarrierObject' DataPlanZoneCarrierObject: properties: apn: description: Carrier APN value for this plan zone type: string nullable: true csp: description: Carrier service provider code (present when includecsp is enabled) type: string nullable: true pop: description: Carrier point of presence (present when includecsp is enabled) type: string nullable: true profile_name: description: Carrier profile display name used by Activation type: string nullable: true profile_short_name: description: Carrier profile short name used by Activation type: string nullable: true type: object securitySchemes: apiKeyAuth: type: http description: >- HTTP Basic authentication using API keys. Set the username to `apikey` and the password to your API key. You can find your API key on the Hologram Dashboard under Account Settings. scheme: basic ````