> ## 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 SIMs,
    accounts, and cloud data. Using this API, you can activate SIMs, get your
    devices' approximate location, send SMS messages to your devices, update
    data usage limits, and much more.


    In Hologram's API, a "device" represents a SIM card. Each item returned by
    `/devices` endpoints represents a single SIM card. You can find more
    information about Hologram terminology in our
    [Glossary](https://docs.hologram.io/guides/get-started/glossary) and the
    Hologram [Connectivity
    overview](https://docs.hologram.io/guides/get-started/sim-connectivity-overview).
    The device ID and SIM ID are effectively the same and represent one SIM, but
    device ID is used in older API endpoints and SIM ID is used in newer API
    endpoints.


    ## Base URL


    ```

    https://dashboard.hologram.io/api/1

    ```


    ## Authentication


    Hologram supports **HTTP Basic authentication** using API keys. Set the
    username to `apikey` and use your API key as the password.


    ### Using cURL


    ```

    curl --verbose GET \

    'https://dashboard.hologram.io/api/1/users/me' \

    -u apikey:YOUR_API_KEY

    ```


    ### Using authorization header


    You can also base64 encode `apikey:YOUR_API_KEY` and include it in the
    Authorization header:


    ```

    curl --verbose GET \

    'https://dashboard.hologram.io/api/1/users/me' \

    --header "Authorization: Basic BASE64_ENCODED_CREDENTIALS"

    ```


    ## API access levels


    - **Read Access**: Available to Editor roles and higher.

    - **Write Access**: Varies by endpoint based on role access, generally
    limited to Admin and Manager roles.


    Users without appropriate permissions will receive 403 errors for restricted
    operations.


    ## Requests


    Request bodies can be provided in either JSON or form-urlencoded formats:


    ### JSON format (recommended)


    ```

    curl --request POST \

    --header "Content-Type: application/json" \

    --header "Authorization: Basic YOUR_ENCODED_CREDENTIALS" \

    --data '{"deviceid": 56668, "body": "Hello SIM!"}' \

    'https://dashboard.hologram.io/api/1/sms/incoming'

    ```


    ### Form-urlencoded format


    ```

    curl --request POST \

    --header "Content-Type: application/x-www-form-urlencoded" \

    --header "Authorization: Basic YOUR_ENCODED_CREDENTIALS" \

    --data 'deviceid=56668&body=Hello%20SIM!' \

    'https://dashboard.hologram.io/api/1/sms/incoming'

    ```


    ## Responses


    **Important:** All Hologram dates and times are stored and displayed in
    **UTC**.


    ### Response format


    All API responses are JSON objects that include the following fields:


    * `success` (boolean) - Indicates whether the request was successful.

    * `data` (object or array) - Contains the requested data or information
    about the operation performed. Only present when `success` is true.

    * `error` (string) - Information about why the request failed. Only present
    when `success` is false.


    ### Limited responses


    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 endpoints have this value built
    in and others often have a maximum value.

    * `size` (number) - The number of values returned by the query.

    * `continues` (boolean, optional) - Only returned if there are more values
    than were returned in the response.

    * `links` (object) - 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.

    ## Rate limiting


    In order to provide a consistent 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.


    ## Generating an API key


    Find your account API key in your
    [dashboard](https://dashboard.hologram.io/settings/api) under the
    **Settings** section in the main menu, then opening the **API** page.


    Your API can be used to access all organizations you are a member of.


    **Caution:** **Keep your API key secure** and never store it in publicly
    accessible places like GitHub repositories.


    ## Organization IDs


    Your API key gives you access to all organizations you are a member of. If
    no organization is specified in an API request, the request will be
    performed for your personal organization.


    Many endpoints accept an `orgid` parameter to filter for SIMs within a
    specific organization. Learn how to find your organization's ID in [this
    guide](https://docs.hologram.io/dashboard/orgs-and-users/organization-overview).


    ## OpenAPI and Swagger links


    OpenAPI -
    [https://dashboard.hologram.io/api/1/docs/openapi.json](https://dashboard.hologram.io/api/1/docs/openapi.json)


    Swagger -
    [https://dashboard.hologram.io/api/1/docs](https://dashboard.hologram.io/api/1/docs)


    ## Support


    For API support, questions, or additional assistance, please [contact our
    support team](https://docs.hologram.io/guides/get-started/contact-support).
  version: '1'
servers:
  - url: https://dashboard.hologram.io/api/1
    description: Hologram REST API v1
security: []
tags:
  - name: SIMs (Devices)
    description: SIMs (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
  - name: Events and Alerts
    description: Events and Alerts
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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.