---
title: "Get single list metadata"
method: GET
path: "/api/lists/{list_name}"
tags: ["Static Lists"]
---

# Get single list metadata

`GET /api/lists/{list_name}`

## Request

- Base URL: `https://go.urbanairship.com`
- URL: `https://go.urbanairship.com/api/lists/{list_name}`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `http://oauth2.{domain}.com/token` scopes: `lst`
- TypeScript: <https://skmtc.dev/airship/apis/airship-api/docs/api/lists/:list_name/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve information about one static list, specified in the URL. When looking up lists, the returned information may actually be a combination of values from both the last uploaded list and the last successfully processed list. If you create a list successfully, and then you update it and the processing step fails, then the list `status` will read `failed`, but the `channel_count` and `last_modified` fields will contain information on the last successfully processed list.

## Path parameters

- `list_name` string, required

## Response `200`

List metadata retrieved successfully.

- ListMetadataResponse
  - `description` string: An optional description for the list.
  - `extra` unknown
  - `name` string: The name of the list, consists of up to 64 URL-safe characters. The name is how the list is identified, so it should be unique and memorable.
  - `ok` boolean: Success.

## Other responses

- `401`: Authentication information (the app key and secret or bearer token) was either incorrect or missing.
- `404`: The requested resource doesn't exist.

## Changes

- **2025-08-28** `3304568aaadc`: 1 breaking
  - the response property `name` became optional for the status `200`
  - …this revision’s changelog is incomplete

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/lists/:list_name/get.md)

---

[API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)