Get Single Send Stats by ID

API Overview

As a Marketing Campaigns customer, you have access to rich statistics about your Single Sends and Automations. The Marketing Campaigns Statistics API allows you to retrieve these statistics programmatically. for detailed information about the statistics available, see the Marketing Campaigns Stats Overview.

(information)

Note

These endpoints provide stats for Marketing Campaigns only. For stats related to event tracking, please see the Stats API.

Operation overview

GET/v3/marketing/stats/singlesends/{id}

Base url: https://api.sendgrid.com (The Twilio SendGrid v3 API)

This endpoint allows you to retrieve stats for an individual Single Send using a Single Send ID.

Multiple Single Send IDs can be retrieved using the "Get All Single Sends Stats" endpoint. Once you have an ID, this endpoint will return detailed stats for the Single Send specified.

You may constrain the stats returned using the start_date and end_date query string parameters. You can also use the group_by and aggregated_by query string parameters to further refine the stats returned.

Operation details

Authentication

API Key

Headers

Property nameTypeRequiredDescription

Authorizationstring

required

Default: Bearer <<YOUR_API_KEY_HERE>>

Path parameters

Property nameTypeRequiredDescription

idstring

required

The ID of Single Send for which you want to retrieve stats.

Query string

Property nameTypeRequiredDescription

aggregated_byenum<string>

Optional

Dictates how the stats are time-sliced. Currently, "total" and "day" are supported.

Default: totalPossible values:

daytotal

start_datestring<date>

Optional

Format: YYYY-MM-DD. If this parameter is included, the stats' start date is included in the search.

Default: 2021-01-01

end_datestring<date>

Optional

Format: YYYY-MM-DD.If this parameter is included, the stats' end date is included in the search.

Default: 2021-12-31

timezonestring

Optional

IANA Area/Region string representing the timezone in which the stats are to be presented, e.g., "America/Chicago".

Default: UTC

page_sizeinteger

Optional

The number of elements you want returned on each page.

Default: 25Minimum: 1Maximum: 50

page_tokenstring

Optional

The stats endpoints are paginated. To get the next page, call the passed _metadata.next URL. If _metadata.prev doesn't exist, you're at the first page. Similarly, if _metadata.next is not present, you're at the last page.

group_byarray[enum<string>]

Optional

A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields.

Possible values:

ab_variationab_phase

Responses

200400404

Schema

Property nameTypeRequiredDescriptionChild properties

resultsarray[object]

Optional

Show results properties

_metadatametadata

Optional

Show _metadata properties

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Optional

Show errors properties

idstring

Optional

When applicable, this property value will be an error ID.

Get Single Send Stats by ID

1const client = require("@sendgrid/client");
2client.setApiKey(process.env.SENDGRID_API_KEY);
3
4const id = "id";
5const queryParams = {
6  aggregated_by: "total",
7  end_date: "2021-12-31",
8  page_size: 25,
9  start_date: "2021-01-01",
10  timezone: "UTC",
11};
12
13const request = {
14  url: `/v3/marketing/stats/singlesends/${id}`,
15  method: "GET",
16  qs: queryParams,
17};
18
19client
20  .request(request)
21  .then(([response, body]) => {
22    console.log(response.statusCode);
23    console.log(response.body);
24  })
25  .catch((error) => {
26    console.error(error);
27  });