> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.brevo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server.

# Get a list's details

GET https://api.brevo.com/v3/contacts/lists/{listId}

Retrieve the details of a specific contact list by its ID, including its name, folder ID, creation date, subscriber counts, and campaign statistics. You can optionally filter campaign statistics by providing startDate and endDate parameters (both must be used together in YYYY-MM-DD format).

Reference: https://developers.brevo.com/reference/get-list

## Authentication

- `api-key` header (required) — The API key should be passed in the request headers as `api-key` for authentication.

## Request

### Path parameters

- `listId` (long, required) — Id of the list

### Query parameters

- `startDate` (string, optional) — **Mandatory if endDate is used**. Starting (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to aggregate the sent email campaigns for a specific list id. **Prefer to pass your timezone in date-time format for accurate result**
- `endDate` (string, optional) — **Mandatory if startDate is used**. Ending (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to aggregate the sent email campaigns for a specific list id. **Prefer to pass your timezone in date-time format for accurate result**

## Response

### 200

List informations

- `id` (long, required) — ID of the list
- `name` (string, required) — Name of the list
- `totalBlacklisted` (long, required) — Number of blacklisted contacts in the list
- `totalSubscribers` (long, required) — Number of contacts in the list
- `uniqueSubscribers` (long, required) — Number of unique contacts in the list
- `createdAt` (string, required) — Creation UTC date-time of the list (YYYY-MM-DDTHH:mm:ss.SSSZ)
- `folderId` (long, required) — ID of the folder
- `campaignStats` (list of object, optional)
  - `campaignId` (long, required) — ID of the campaign
  - `stats` (object, required)
    - `appleMppOpens` (long, required, nullable) — Numbers of times your email has been opened automatically through Apple MPP.
    - `clickers` (long, required, nullable) — Number of total clicks for the campaign
    - `complaints` (long, required, nullable) — Number of complaints (Spam reports) for the campaign
    - `delivered` (long, required, nullable) — Number of delivered emails for the campaign
    - `hardBounces` (long, required, nullable) — Number of hard bounces for the campaign
    - `opensRate` (float, required, nullable) — Percentage of recipients who open the email out of your total number of recipients. Depending on your Campaign settings, they may include Apple MPP opens.
    - `sent` (long, required, nullable) — Number of sent emails for the campaign
    - `softBounces` (long, required, nullable) — Number of softbounce for the campaign
    - `trackableViews` (long, required, nullable) — Recipients without any privacy protection option enabled in their email email client
    - `uniqueClicks` (long, required, nullable) — Number of unique clicks for the campaign
    - `uniqueViews` (long, required, nullable) — Number of unique openings for the campaign
    - `unsubscriptions` (long, required, nullable) — Number of unsubscription for the campaign
    - `viewed` (long, required, nullable) — Number of openings for the campaign
    - `deferred` (long, optional) — Number of deferred emails for the campaign
    - `estimatedViews` (long, optional) — Rate of recipients without any privacy protection option enabled in their email client, applied to all delivered emails
    - `listId` (long, optional) — List Id of email campaign (only in case of get email campaign(s)(not for global stats))
    - `returnBounce` (long, optional) — Total number of non-delivered campaigns for a particular campaign id.
    - `trackableViewsRate` (float, optional) — Rate of recipients without any privacy protection option enabled in their email client
- `dynamicList` (boolean, optional) — Status telling if the list is dynamic or not (true=dynamic, false=not dynamic)

## Errors

### 400 Bad Request Error

bad request

- `code` (enum, required) — Error code displayed in case of a failure
  - Allowed values: `invalid_parameter`, `missing_parameter`, `out_of_range`, `campaign_processing`, `campaign_sent`, `document_not_found`, `not_enough_credits`, `permission_denied`, `duplicate_parameter`, `duplicate_request`, `method_not_allowed`, `unauthorized`, `account_under_validation`, `not_acceptable`, `bad_request`, `unprocessable_entity`, `Domain does not exist`, `Contact email not found`, `Attribute not found`, `Category id not found`, `Invalid parameters passed`, `Record(s) for identifier not found`, `Returned when query params are invalid`, `Returned when invalid data posted`, `Feed not found`, `Campaign ID not found`, `api-key not found`, `DMARC policy requires domain authentication`, `DNS records not properly configured`, `Invalid OTP code provided`, `OTP code has expired`, `Domain already exists in your account`, `The sum of all IP weights must equal 100`, `Authentication failed`, `Insufficient credits`, `Request already processed`
- `message` (string, required) — Readable message associated to the failure

### 404 Not Found Error

List ID not found

- `message` (string, required) — Readable message associated to the failure
- `code` (string, optional) — Error code displayed in case of a failure

## Examples

**Response**

```json
{
  "id": 12,
  "name": "Newsletter_Weekly",
  "totalBlacklisted": 63,
  "totalSubscribers": 6533,
  "uniqueSubscribers": 6596,
  "createdAt": "2016-02-26T11:56:08Z",
  "folderId": 1,
  "campaignStats": [
    {
      "campaignId": 15,
      "stats": {
        "appleMppOpens": 10,
        "clickers": 789,
        "complaints": 0,
        "delivered": 6632,
        "hardBounces": 4,
        "opensRate": 29.54,
        "sent": 6645,
        "softBounces": 34,
        "trackableViews": 5661,
        "uniqueClicks": 701,
        "uniqueViews": 3442,
        "unsubscriptions": 4,
        "viewed": 4322,
        "deferred": 0
      }
    },
    {
      "campaignId": 45,
      "stats": {
        "appleMppOpens": 10,
        "clickers": 788,
        "complaints": 1,
        "delivered": 4078,
        "hardBounces": 2,
        "opensRate": 29.54,
        "sent": 4334,
        "softBounces": 18,
        "trackableViews": 5661,
        "uniqueClicks": 654,
        "uniqueViews": 987,
        "unsubscriptions": 4,
        "viewed": 1555,
        "deferred": 0
      }
    }
  ],
  "dynamicList": false,
  "endDate": "2024-04-10T00:00:00Z",
  "startDate": "2023-10-10T00:00:00Z"
}
```

**SDK Code**

```typescript response
import { BrevoClient } from "@getbrevo/brevo";

async function main() {
    const client = new BrevoClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.contacts.getList({
        listId: 1,
    });
}
main();

```

```python response
from brevo import Brevo

client = Brevo(
    api_key="YOUR_API_KEY_HERE",
)

client.contacts.get_list(
    list_id=1,
)

```

```php response
<?php

namespace Example;

use Brevo\Brevo;
use Brevo\Contacts\Requests\GetListRequest;

$client = new Brevo(
    apiKey: 'YOUR_API_KEY_HERE',
);
$client->contacts->getList(
    1,
    new GetListRequest([]),
);

```

```go response
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.brevo.com/v3/contacts/lists/1"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby response
require 'uri'
require 'net/http'

url = URI("https://api.brevo.com/v3/contacts/lists/1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java response
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.brevo.com/v3/contacts/lists/1")
  .header("api-key", "<apiKey>")
  .asString();
```

```csharp response
using RestSharp;

var client = new RestClient("https://api.brevo.com/v3/contacts/lists/1");
var request = new RestRequest(Method.GET);
request.AddHeader("api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift response
import Foundation

let headers = ["api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.brevo.com/v3/contacts/lists/1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```