# Get a List by ID

## API Overview

Lists are static collections of Marketing Campaigns contacts. This API allows you to interact with the list objects themselves. To add contacts to a list, you must use the [Contacts API](/docs/sendgrid/api-reference/contacts/add-or-update-a-contact).

You can also manage your lists using the [Contacts menu in the Marketing Campaigns UI](https://mc.sendgrid.com/contacts). For more information about lists and best practices for building them, see ["Building your Contact List"](/docs/sendgrid/ui/managing-contacts/building-your-contact-list/).

## Operation overview

```json
{"path":"https://api.sendgrid.com/v3/marketing/lists/{id}","method":"get","servers":[{"url":"https://api.sendgrid.com","description":"The Twilio SendGrid v3 API"}]}
```

**This endpoint returns data about a specific list.**
Setting the optional parameter `contact_sample=true` returns the `contact_sample` in the response body. Up to 50 of the most recent contacts uploaded or attached to a list will be returned.
The full contact count is also returned.

## Operation details

### Authentication

API Key

### Headers

```json
[{"in":"header","name":"Authorization","required":true,"default":"Bearer <<YOUR_API_KEY_HERE>>","schema":{"type":"string"}}]
```

### Path parameters

```json
[{"name":"id","in":"path","required":true,"description":"The ID of the list on which you want to perform the operation.","schema":{"type":"string"}}]
```

### Query string

```json
[{"name":"contact_sample","in":"query","description":"Setting this parameter to the true  will cause the contact_sample to be returned","schema":{"type":"boolean","default":false}}]
```

### Responses

```json
[{"responseCode":"200","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The generated ID for your list.","minLength":36,"maxLength":36},"name":{"type":"string","description":"The name you gave your list."},"contact_count":{"type":"integer","description":"The number of contacts currently stored on the list."},"_metadata":{"title":"selfMetadata","type":"object","refName":"SelfMetadata","modelName":"SelfMetadata","properties":{"self":{"type":"string","description":"A link to this object."}}},"contact_sample":{"title":"contact-details2","type":"object","required":["id","list_ids","created_at","updated_at"],"refName":"ContactDetails","modelName":"ContactDetails","properties":{"id":{"type":"string","minLength":36,"maxLength":36,"format":"uuid"},"first_name":{"type":"string"},"last_name":{"type":"string"},"unique_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone_number_id":{"type":"string"},"external_id":{"type":"string"},"anonymous_id":{"type":"string"},"alternate_emails":{"nullable":true,"type":"array","items":{"type":"string","format":"email"}},"address_line_1":{"type":"string"},"address_line_2":{"type":"string"},"city":{"type":"string"},"state_province_region":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"},"phone_number":{"type":"string"},"whatsapp":{"type":"string"},"line":{"type":"string"},"facebook":{"type":"string"},"list_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"segment_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"custom_fields":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"_metadata":{"title":"selfMetadata","type":"object","refName":"SelfMetadata","modelName":"SelfMetadata","properties":{"self":{"type":"string","description":"A link to this object."}}}}}}},"examples":{"response":{"value":{"contact_count":2,"contact_sample":{"id":"c3445f88-5c69-4237-86e6-9ec9de958050","list_ids":["199abb98-0af3-4a8d-b371-6811ff85d062"],"created_at":"2620-06-16T17:03:54.867Z","updated_at":"4780-12-06T06:51:30.024Z"},"_metadata":{"self":"https://api.sendgrid.com/v3/marketing/lists/199abb98-0af3-4a8d-b371-6811ff85d062"},"id":"199abb98-0af3-4a8d-b371-6811ff85d062","name":"list-name"}}}}}}},{"responseCode":"404","schema":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"title":"error","type":"object","required":["message"],"refName":"Error","modelName":"Error","properties":{"message":{"type":"string"},"field":{"type":"string"},"error_id":{"type":"string"},"parameter":{"type":"string"}}}}}}}}]
```

Get a List by ID

```js
const client = require("@sendgrid/client");
client.setApiKey(process.env.SENDGRID_API_KEY);

const id = "id";

const request = {
  url: `/v3/marketing/lists/${id}`,
  method: "GET",
};

client
  .request(request)
  .then(([response, body]) => {
    console.log(response.statusCode);
    console.log(response.body);
  })
  .catch((error) => {
    console.error(error);
  });
```

```python
import os
from sendgrid import SendGridAPIClient


sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY"))

id = "id"

response = sg.client.marketing.lists._(id).get()

print(response.status_code)
print(response.body)
print(response.headers)
```

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SendGrid;

public class Program {
    public static async Task Main() {
        string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
        var client = new SendGridClient(apiKey);

        var id = "id";

        var response = await client.RequestAsync(
            method: SendGridClient.Method.GET, urlPath: $"marketing/lists/{id}");

        Console.WriteLine(response.StatusCode);
        Console.WriteLine(response.Body.ReadAsStringAsync().Result);
        Console.WriteLine(response.Headers.ToString());
    }
}
```

```java
import com.sendgrid.*;
import java.io.IOException;

public class Example {
    public static void main(String[] args) throws IOException {
        try {
            SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
            Request request = new Request();
            request.setMethod(Method.GET);
            request.setEndpoint("/marketing/lists/id");
            Response response = sg.api(request);
            System.out.println(response.getStatusCode());
            System.out.println(response.getBody());
            System.out.println(response.getHeaders());
        } catch (IOException ex) {
            throw ex;
        }
    }
}
```

```go
package main

import (
	"fmt"
	"github.com/sendgrid/sendgrid-go"
	"os"
)

func main() {
	apiKey := os.Getenv("SENDGRID_API_KEY")
	host := "https://api.sendgrid.com"
	request := sendgrid.GetRequest(apiKey, "/v3/marketing/lists/id", host)
	request.Method = "GET"
	response, err := sendgrid.API(request)
	if err != nil {
		fmt.Println(err.Error())
		os.Exit(1)
	} else {
		fmt.Println(response.StatusCode)
		fmt.Println(response.Body)
		fmt.Println(response.Headers)
	}
}
```

```php
<?php
// Uncomment the next line if you're using a dependency loader (such as Composer) (recommended)
// require 'vendor/autoload.php';

// Uncomment next line if you're not using a dependency loader (such as Composer)
// require_once '<PATH TO>/sendgrid-php.php';

$apiKey = getenv("SENDGRID_API_KEY");
$sg = new \SendGrid($apiKey);
$id = "id";

try {
    $response = $sg->client
        ->marketing()
        ->lists()
        ->_($id)
        ->get();
    print $response->statusCode() . "\n";
    print_r($response->headers());
    print $response->body() . "\n";
} catch (Exception $ex) {
    echo "Caught exception: " . $ex->getMessage();
}
```

```ruby
require 'sendgrid-ruby'
include SendGrid

sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'])
id = "id"

response = sg.client.marketing.lists._(id).get()
puts response.status_code
puts response.headers
puts response.body
```

```bash
curl -X GET "https://api.sendgrid.com/v3/marketing/lists/id" \
--header "Authorization: Bearer $SENDGRID_API_KEY"
```