> ## 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.

# Update SIM usage limits

> Updates the data usage limit, SMS limit, and data warning threshold for a SIM using the device ID for the SIM. Values must be >= -1, where -1 means no limit.

Data usage limits are applied above the included data in the SIM's data plan; a 500 MB data plan with a 250 MB data limit will trigger an event when the SIM uses 750 MB of data.

SMS limits can be reduced, or raised back up to your organization's maximum SMS limit.



## OpenAPI

````yaml /api/1/openapi.yaml post /devices/{deviceId}/usagelimit
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:
  /devices/{deviceId}/usagelimit:
    post:
      tags:
        - SIMs (Devices)
      summary: Update SIM usage limits
      description: >-
        Updates the data usage limit, SMS limit, and data warning threshold for
        a SIM using the device ID for the SIM. Values must be >= -1, where -1
        means no limit.


        Data usage limits are applied above the included data in the SIM's data
        plan; a 500 MB data plan with a 250 MB data limit will trigger an event
        when the SIM uses 750 MB of data.


        SMS limits can be reduced, or raised back up to your organization's
        maximum SMS limit.
      operationId: changeDeviceUsageLimitSingle
      parameters:
        - name: deviceId
          in: path
          description: ID of the device
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                datathreshold:
                  description: >-
                    Data warning threshold in bytes; an event is created when
                    data usage reaches this value (-1 for no limit)
                  type: number
                  minimum: -1
                  example: 1000000
                overagelimit:
                  description: >-
                    Additional bytes of data allowed above the plan's included
                    data; SIM pauses when usage exceeds plan included data plus
                    this value (-1 for unlimited, 0 for plan included data only)
                  type: number
                  minimum: -1
                  example: 2000000
                smslimit:
                  description: >-
                    Maximum number of SMS messages allowed, within the
                    organization's SMS limit; SIM is paused when this limit is
                    reached
                  type: number
                  minimum: -1
                  example: 100
              type: object
              anyOf:
                - required:
                    - datathreshold
                - required:
                    - overagelimit
                - required:
                    - smslimit
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  success:
                    $ref: '#/components/schemas/SuccessProperty'
                  data:
                    properties:
                      warnings:
                        type: array
                        items:
                          type: string
                      devices_modified:
                        description: IDs of devices whose usage limit was updated
                        type: array
                        items:
                          type: integer
                      profiles_modified:
                        description: IDs of SIM profiles whose usage limit was updated
                        type: array
                        items:
                          type: integer
                      newdatathreshold:
                        description: >-
                          Updated data warning threshold in bytes (-1 for no
                          threshold)
                        type: number
                      newoveragelimit:
                        description: >-
                          Updated data overage limit in bytes above the plan's
                          included data (-1 for unlimited)
                        type: number
                      newsmslimit:
                        description: Updated SMS limit
                        type: number
                    type: object
                type: object
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
        - apiKeyAuth: []
components:
  schemas:
    SuccessProperty:
      description: Indicates whether the request was successful.
      type: boolean
      example: true
  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.