Skip to content
Alchemy Logo

Admin API Quickstart

Create an app and query usage with the Admin API.

This guide walks through creating an app, updating its configuration, and querying account usage.

  • An access key with App Management write permissions 

export ALCHEMY_ADMIN_BASE_URL="https://admin-api.alchemy.com/v1"
export ALCHEMY_ADMIN_ACCESS_KEY="YOUR_ACCESS_KEY_HERE"

Auth header:

export ALCHEMY_ADMIN_AUTH_HEADER="Authorization: Bearer $ALCHEMY_ADMIN_ACCESS_KEY"

Retrieve the list of supported networks and their identifiers. These values are required when you configure network allowlists.

curl "$ALCHEMY_ADMIN_BASE_URL/chains" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER"

See the List chains endpoint for response fields.

Create a new app by providing a name, description, and supported networks.

curl -X POST "$ALCHEMY_ADMIN_BASE_URL/apps" \
  -H "Content-Type: application/json" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
  -d '{
    "name": "My App",
    "description": "Example app",
    "networkAllowlist": ["ETH_MAINNET", "ARB_MAINNET"],
    "products": ["node-api", "webhooks"]
  }'

Example response:

{
  "data": {
    "id": "k5c99fzeegrljz2i",
    "name": "Test App",
    "description": "App for full workflow test",
    "apiKey": "Ow7sB2EbdOgDvAU5P3N0V",
    "webhookApiKey": "1JIfTRjWbCv4gZS2IWEyTxKHO8eqa2C7",
    "chainNetworks": [
      {
        "name": "Ethereum Mainnet",
        "id": "ETH_MAINNET",
        "networkChainId": "1",
        "rpcUrl": "https://eth-mainnet.g.alchemy.com/v2/Ow7sB2EbdOgDvAU5P3N0V",
        "wsUrl": "wss://eth-mainnet.g.alchemy.com/v2/Ow7sB2EbdOgDvAU5P3N0V"
      }
    ],
    "products": [],
    "addressAllowlist": [],
    "originAllowlist": [],
    "ipAllowlist": [],
    "createdAt": "2026-02-05T16:03:03.121+00:00"
  }
}

See the Create app endpoint for request options.

Retrieve details for a single app using its app_id.

APP_ID="app_123"
 
curl "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER"

App updates are split between metadata updates and configuration updates.

  • Use PATCH /apps/{app_id} to update name or description
  • Use configuration sub-endpoints to update networks, allowlists, and IP restrictions

APP_ID="app_123"
 
curl -X PATCH "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID" \
  -H "Content-Type: application/json" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
  -d '{
    "name": "Renamed App",
    "description": "Updated description"
  }'

Update the set of networks this app is allowed to access. Network values must come from the Chains endpoint. The networks you provide replace the current list.

APP_ID="app_123"
 
curl -X PUT "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID/networks" \
  -H "Content-Type: application/json" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
  -d '{
    "networkAllowlist": ["ETH_MAINNET", "OPT_MAINNET"]
  }'

Update the origin URLs available for this app.

APP_ID="app_123"
 
curl -X PUT "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID/origin-allowlist" \
  -H "Content-Type: application/json" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
  -d '{
    "originAllowlist": [
      { "name": "Test Origin", "value": "https://example.com" }
    ]
  }'

Update the IP addresses that can send requests via this app.

APP_ID="app_123"
 
curl -X PUT "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID/ip-allowlist" \
  -H "Content-Type: application/json" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
  -d '{
    "ipAllowlist": [
      { "name": "Test IP", "value": "203.0.113.1" }
    ]
  }'

Retrieve usage totals for the current billing period and recent rolling windows.

curl "$ALCHEMY_ADMIN_BASE_URL/usage/summary" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER"

Example response:

{
  "data": {
    "billingPeriod": {
      "startTime": "2026-06-01T00:00:00Z",
      "endTime": "2026-07-01T00:00:00Z"
    },
    "totals": {
      "last7Days": {
        "amount": "1250000",
        "unit": "ALCHEMY_COMPUTE_UNIT",
        "usd": "12.50"
      },
      "last30Days": {
        "amount": "4800000",
        "unit": "ALCHEMY_COMPUTE_UNIT",
        "usd": "48.00"
      },
      "monthToDate": {
        "amount": "3200000",
        "unit": "ALCHEMY_COMPUTE_UNIT",
        "usd": "32.00"
      }
    },
    "usageLimit": {
      "unit": "CU",
      "limit": "10000000",
      "used": "3200000",
      "remaining": "6800000",
      "percentUsed": 32
    },
    "freshness": {
      "dataThrough": "2026-06-28T23:59:00Z",
      "containsPartialToday": true,
      "updateCadence": "minute"
    }
  }
}

See the Get usage summary endpoint for response fields.

Query daily usage over a date range. You can optionally filter by app, network, method, or request type, and group results by up to three dimensions.

The products values are listed in Time series products. If you omit products, the API uses SUPERNODE_CU.

curl -X POST "$ALCHEMY_ADMIN_BASE_URL/usage/time-series" \
  -H "Content-Type: application/json" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
  -d '{
    "startTime": "2026-06-01T00:00:00Z",
    "endTime": "2026-06-07T23:59:59Z",
    "granularity": "day",
    "products": ["SUPERNODE_CU"],
    "metrics": ["amount"],
    "groupBy": ["network"]
  }'

Example response:

{
  "data": {
    "query": {
      "startTime": "2026-06-01T00:00:00Z",
      "endTime": "2026-06-07T23:59:59Z",
      "granularity": "day",
      "products": ["SUPERNODE_CU"],
      "metrics": ["amount"],
      "groupBy": ["network"]
    },
    "freshness": {
      "dataThrough": "2026-06-07T23:59:00Z",
      "containsPartialToday": false,
      "updateCadence": "minute"
    },
    "data": [
      {
        "startTime": "2026-06-01T00:00:00Z",
        "endTime": "2026-06-02T00:00:00Z",
        "isPartial": false,
        "dimensions": {
          "network": "eth-mainnet"
        },
        "amount": "450000",
        "unit": "ALCHEMY_COMPUTE_UNIT"
      }
    ]
  }
}

See the Get usage time series endpoint for request options.

Permanently delete an app. This action cannot be undone.

APP_ID="app_123"
 
curl -X DELETE "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID" \
  -H "$ALCHEMY_ADMIN_AUTH_HEADER"

  • Use the Alchemy CLI to query usage from the terminal without writing HTTP requests
Was this page helpful?