# Get List of Segments

## API Overview

Segments are similar to contact lists, except they update dynamically over time as information stored about your contacts or the criteria used to define your segments changes. When you segment your audience, you are able to create personalized Automation emails and Single Sends that directly address the wants and needs of your particular audience.

The Marketing Campaigns Segments V2 API allows you to create, edit, and delete segments as well as retrieve a list of segments or an individual segment by ID.

Segments built using engagement data such as "was sent" or "clicked" will take approximately 30 minutes to begin populating.

Segment samples and counts refresh on a schedule that ranges from 1 to 24 hours. Segments with active automations or that are used as exclusion lists for scheduled Single Sends refresh every hour. Segments that aren't actively used refresh less frequently, up to every 24 hours, to optimize processing resources. Samples and counts displayed in the UI don't update immediately when segment criteria are modified or when contacts are added or updated. Instead, they update according to the segment's refresh schedule.

## Operation overview

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

**This endpoint allows you to retrieve a list of segments.**

The query param `parent_list_ids` is treated as a filter.  Any match will be returned.  Zero matches will return a response code of 200 with an empty `results` array.

| `parent_list_ids` | `no_parent_list_id` | `ids` |                                  `result`                                  |
| ----------------: | :-----------------: | :---: | :------------------------------------------------------------------------: |
|             empty |        false        | empty |                             all segments values                            |
|         list\_ids |        false        | empty |                    segments filtered by list\_ids values                   |
|         list\_ids |         true        | empty | segments filtered by list\_ids and segments with no parent list\_ids empty |
|             empty |         true        | empty |                      segments with no parent list\_ids                     |
|          anything |       anything      |  ids  |                     segments with matching segment ids                     |

## Operation details

### Authentication

API Key

### Headers

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

### Query string

```json
[{"name":"ids","in":"query","description":"A list of segment IDs to retrieve. When this parameter is included, the `no_parent_list_ids` and `parent_list_ids` parameters are ignored and only segments with given IDs are returned.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"parent_list_ids","in":"query","description":"A comma separated list up to 50 in size, to filter segments on.  Only segments that have any of these list ids as the parent list will be retrieved. This is different from the parameter of the same name used when creating a segment.","required":false,"schema":{"type":"string"}},{"name":"no_parent_list_id","in":"query","description":"If set to `true`, segments with an empty value of `parent_list_id` will be returned in the filter.  If the value is not present, it defaults to 'false'.","required":false,"schema":{"type":"boolean","default":false}}]
```

### Responses

```json
[{"responseCode":"200","schema":{"description":"","content":{"application/json":{"schema":{"title":"all_segments_response","type":"object","required":["id","name","contacts_count","created_at","updated_at","sample_updated_at","next_sample_update","parent_list_ids","query_version","status"],"refName":"AllSegments200","modelName":"AllSegments200","properties":{"id":{"type":"string","minLength":36,"maxLength":36,"format":"uuid","description":"ID assigned to the segment when created."},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name of the segment."},"contacts_count":{"type":"integer","description":"Total number of contacts present in the segment"},"created_at":{"type":"string","description":"ISO8601 timestamp of when the object was created"},"updated_at":{"type":"string","description":"ISO8601 timestamp of when the object was last updated"},"sample_updated_at":{"type":"string","description":"ISO8601 timestamp of when the samples were last updated"},"next_sample_update":{"type":"string","description":"ISO8601 timestamp of when the samples will be next updated"},"parent_list_ids":{"type":"array","description":"The array of list ids to filter contacts on when building this segment. It allows only one such list id for now. We will support more in future","uniqueItems":true,"items":{"type":"string"}},"query_version":{"type":"string","description":"If not set, segment contains a query for use with Segment v1 APIs. If set to '2', segment contains a SQL query for use in v2."},"_metadata":{"title":"_metadata","type":"object","refName":"Metadata","modelName":"Metadata","properties":{"prev":{"type":"string","format":"uri"},"self":{"type":"string","format":"uri"},"next":{"type":"string","format":"uri"},"count":{"type":"integer","minimum":0}}},"status":{"title":"segment_status_response","type":"object","description":"Segment status indicates whether the segment's contacts will be updated periodically","required":["query_validation"],"refName":"SegmentStatusResponse","modelName":"SegmentStatusResponse","properties":{"query_validation":{"type":"string","description":"Status of query validation. PENDING, VALID, or INVALID"},"error_message":{"type":"string","description":"Describes any errors that were encountered during query validation"}}}}}}}}},{"responseCode":"400","schema":{"description":"","content":{"application/json":{"schema":{"title":"errors-seg","type":"object","description":"If the request is incorrect, an array of errors will be returned.","required":["errors"],"refName":"ErrorsSegmentV2","modelName":"ErrorsSegmentV2","properties":{"errors":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string","description":"the field in the request body that is incorrect"},"message":{"type":"string","description":"a description of what is specifically wrong with the field passed in the request"}}}}}}}}}},{"responseCode":"404","schema":{"description":""}},{"responseCode":"500","schema":{"description":"","content":{"application/json":{"schema":{"title":"errors-seg","type":"object","description":"If the request is incorrect, an array of errors will be returned.","required":["errors"],"refName":"ErrorsSegmentV2","modelName":"ErrorsSegmentV2","properties":{"errors":{"type":"array","items":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string","description":"the field in the request body that is incorrect"},"message":{"type":"string","description":"a description of what is specifically wrong with the field passed in the request"}}}}}}}}}}]
```

Get List of Segments

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

const request = {
  url: `/v3/marketing/segments/2.0`,
  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"))


response = sg.client._("marketing/segments/2.0").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 response = await client.RequestAsync(
            method: SendGridClient.Method.GET, urlPath: "marketing/segments/2.0");

        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/segments/2.0");
            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/segments/2.0", 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);

try {
    $response = $sg->client->_("marketing/segments/2.0")->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'])

response = sg.client._("marketing/segments/2.0").get()
puts response.status_code
puts response.headers
puts response.body
```

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