openapi: 3.1.0
info:
title: Twilio SendGrid Provisioning Account Stats API
summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.
You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: account_provisioning
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Stats
description: Twilio SendGrid Marketing Campaigns Stats API
paths:
/v3/marketing/stats/automations:
get:
operationId: ListAutomationStat
summary: Get All Automation Stats
tags:
- Stats
description: '**This endpoint allows you to retrieve stats for all your Automations.**
By default, all of your Automations will be returned, but you can specify a selection by passing in a comma-separated list of Automation IDs as the value of the query string parameter `automation_ids`.
Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 25, but you can specify a value between 1 and 50.
You can retrieve a specific page of responses with the `page_token` query string parameter.'
parameters:
- name: automation_ids
in: query
description: This endpoint returns all automation IDs if no `automation_ids` are specified.
style: form
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 25
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AutomationsResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v3/marketing/stats/automations/{id}:
parameters:
- name: id
in: path
description: 'The ID of the Automation for which you want to retrieve statistics. '
required: true
schema:
type: string
get:
operationId: GetAutomationStat
summary: Get Automation Stats by ID
tags:
- Stats
description: '**This endpoint allows you to retrieve stats for a single Automation using its ID.**
Multiple Automation IDs can be retrieved using the "Get All Automation Stats" endpoint. Once you have an ID, this endpoint will return detailed stats for the single automation 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.'
parameters:
- $ref: '#/components/parameters/AutomationQueryParamsGroupBy'
- $ref: '#/components/parameters/AutomationQueryParamsStepId'
- $ref: '#/components/parameters/AggregatedByBaseProps'
- $ref: '#/components/parameters/StartDateBaseProps'
- $ref: '#/components/parameters/EndDateBaseProps'
- $ref: '#/components/parameters/TimezoneBaseProps'
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AutomationsResponse'
'400':
$ref: '#/components/responses/Stats400'
'404':
description: ''
/v3/marketing/stats/automations/{id}/links:
parameters:
- name: id
in: path
description: 'The ID of the Automation you want to get click tracking stats for. '
required: true
schema:
type: string
format: uuid
get:
operationId: ListClickTrackingStat
summary: Get Automation Click Tracking Stats by ID
tags:
- Stats
description: '**This endpoint lets you retrieve click-tracking stats for a single Automation**.
The stats returned list the URLs embedded in your Automation and the number of clicks each one received.'
parameters:
- $ref: '#/components/parameters/AutomationQueryParamsGroupBy'
- $ref: '#/components/parameters/AutomationQueryParamsStepId'
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AutmoationsLinkStatsResponse'
'400':
$ref: '#/components/responses/Stats400'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v3/marketing/stats/automations/export:
get:
operationId: ExportAutomationStat
summary: Export Single Send Stats
tags:
- Stats
description: '**This endpoint allows you to export Single Send stats as .CSV data**.
You can specify one Single Send or many: include as many Single Send IDs as you need, separating them with commas, as the value of the `ids` query string parameter.
The data is returned as plain text response but in .CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a .csv file.'
parameters:
- name: ids
in: query
description: The IDs of Single Sends for which to export stats.
style: form
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 50
- name: timezone
in: query
description: The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_timezones) string representing the timezone in which the stats are to be presented; i.e. `"America/Chicago"`. This parameter changes the timezone format only; it does not alter which stats are returned.
schema:
type: string
default: UTC
responses:
'200':
description: ''
content:
application/json:
schema:
type: string
description: CSV data
'400':
description: ''
/v3/marketing/stats/singlesends:
get:
operationId: ListSingleSendStat
summary: Get All Single Sends Stats
tags:
- Stats
description: '**This endpoint allows you to retrieve stats for all your Single Sends.**
By default, all of your Single Sends will be returned, but you can specify a selection by passing in a comma-separated list of Single Send IDs as the value of the query string parameter `singlesend_ids`.
Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 25, but you specify a value between 1 and 50.
You can retrieve a specific page of responses with the `page_token` query string parameter.'
parameters:
- name: singlesend_ids
in: query
description: This endpoint returns all Single Send IDs if no IDs are included in `singlesend_ids`.
style: form
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 25
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SinglesendsResponse'
'400':
$ref: '#/components/responses/Stats400'
/v3/marketing/stats/singlesends/{id}:
parameters:
- name: id
in: path
description: The ID of Single Send for which you want to retrieve stats.
required: true
schema:
type: string
get:
operationId: GetSingleSendStat
summary: Get Single Send Stats by ID
tags:
- Stats
description: '**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.'
parameters:
- $ref: '#/components/parameters/AggregatedByBaseProps'
- $ref: '#/components/parameters/StartDateBaseProps'
- $ref: '#/components/parameters/EndDateBaseProps'
- $ref: '#/components/parameters/TimezoneBaseProps'
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
- $ref: '#/components/parameters/SinglesendQueryParamsGroupBy'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SinglesendsResponse'
'400':
$ref: '#/components/responses/Stats400'
'404':
description: ''
/v3/marketing/stats/singlesends/{id}/links:
parameters:
- name: id
in: path
description: The ID of Single Send for which you want to retrieve link stats.
required: true
schema:
type: string
get:
operationId: ListSingleSendTrackingStat
summary: Get Single Send Click Tracking Stats by ID
tags:
- Stats
description: '**This endpoint lets you retrieve click-tracking stats for one Single Send**.
The stats returned list the URLs embedded in the specified Single Send and the number of clicks each one received.'
parameters:
- $ref: '#/components/parameters/PaginationPageSize'
- $ref: '#/components/parameters/PaginationPageToken'
- $ref: '#/components/parameters/SinglesendQueryParams2GroupBy'
- $ref: '#/components/parameters/SinglesendQueryParams2VariationId'
- $ref: '#/components/parameters/SinglesendQueryParams2PhaseId'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SinglesendsLinkStatsResponse'
'400':
$ref: '#/components/responses/Stats400'
'404':
description: ''
content:
application/json:
schema:
type: object
/v3/marketing/stats/singlesends/export:
get:
operationId: ExportSingleSendStat
summary: Export Single Send Stats
tags:
- Stats
description: '**This endpoint allows you to export Single Send stats as .CSV data**.
You can specify one Single Send or many: include as many Single Send IDs as you need, separating them with commas, as the value of the `ids` query string parameter.
The data is returned as plain text response but in .CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a .csv file.'
parameters:
- name: ids
in: query
description: The IDs of Single Sends for which to export stats.
style: form
explode: false
schema:
type: array
items:
type: string
minItems: 1
maxItems: 50
- name: timezone
in: query
description: The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_timezones) string representing the timezone in which the stats are to be presented; i.e. `"America/Chicago"`. This parameter changes the timezone format only; it does not alter which stats are returned.
schema:
type: string
default: UTC
responses:
'200':
description: ''
content:
application/json:
schema:
type: string
description: CSV data
'400':
description: ''
/v3/browsers/stats:
get:
operationId: ListBrowserStat
summary: Retrieve email statistics by browser.
tags:
- Stats
description: '**This endpoint allows you to retrieve your email statistics segmented by browser type.**
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).'
parameters:
- name: browsers
in: query
description: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times.
schema:
type: string
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetLimit'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetOffset'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetAggregatedBy'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetStartDate'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetEndDate'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
description: The date that the statistics were gathered.
stats:
type: array
description: The list of statistics.
items:
type: object
properties:
type:
type: string
description: The type of segmentation.
name:
type: string
description: The name of the specific segmentation.
metrics:
$ref: '#/components/schemas/AdvancedStatsClicks'
examples:
response:
value:
- date: '2014-10-01'
stats:
- metrics:
clicks: 0
unique_clicks: 0
name: Chrome
type: browser
- metrics:
clicks: 1
unique_clicks: 1
name: Firefox
type: browser
- date: '2014-10-02'
stats:
- metrics:
clicks: 0
unique_clicks: 0
name: Chrome
type: browser
- metrics:
clicks: 1
unique_clicks: 1
name: Firefox
type: browser
/v3/clients/stats:
get:
operationId: ListClientStat
summary: Retrieve email statistics by client type.
tags:
- Stats
description: '**This endpoint allows you to retrieve your email statistics segmented by client type.**
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsStartDate'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsEndDate'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsAggregatedBy'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
description: The date that the statistics were gathered.
stats:
type: array
description: The list of statistics.
items:
type: object
properties:
type:
type: string
description: The type of segmentation.
name:
type: string
description: The name of the specific segmentation.
metrics:
$ref: '#/components/schemas/AdvancedStatsOpens'
examples:
response:
value:
- date: '2014-10-01'
stats:
- metrics:
opens: 1
unique_opens: 1
name: Gmail
type: client
- date: '2014-10-02'
stats:
- metrics:
opens: 0
unique_opens: 0
name: Gmail
type: client
/v3/clients/{client_type}/stats:
parameters:
- name: client_type
in: path
description: Specifies the type of client to retrieve stats for. Must be either "phone", "tablet", "webmail", or "desktop".
required: true
schema:
type: string
$ref: '#/components/schemas/ClientType'
get:
operationId: GetClientStat
summary: Retrieve stats by a specific client type.
tags:
- Stats
description: '**This endpoint allows you to retrieve your email statistics segmented by a specific client type.**
**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.
### Available Client Types
- phone
- tablet
- webmail
- desktop
Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsStartDate'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsEndDate'
- $ref: '#/components/parameters/StatsAdvancedStatsBaseQueryStringsAggregatedBy'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
description: The date that the statistics were gathered.
stats:
type: array
description: The list of statistics.
items:
type: object
properties:
type:
type: string
description: The type of segmentation.
name:
type: string
description: The name of the specific segmentation.
metrics:
$ref: '#/components/schemas/AdvancedStatsOpens'
examples:
response:
value:
- date: '2014-10-01'
stats:
- metrics:
opens: 1
unique_opens: 1
name: Gmail
type: client
- date: '2014-10-02'
stats:
- metrics:
opens: 0
unique_opens: 0
name: Gmail
type: client
/v3/devices/stats:
get:
operationId: ListDeviceStat
summary: Retrieve email statistics by device type.
tags:
- Stats
description: "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/)."
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetLimit'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetOffset'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetAggregatedBy'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetStartDate'
- $ref: '#/components/parameters/StatsAdvancedQueryStringsLimitOffsetEndDate'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
date:
type: string
description: The date that the statistics were gathered.
stats:
type: array
description: The list of statistics.
items:
type: object
properties:
type:
type: string
description: The type of segmentation.
name:
type: string
description: The name of the specific segmentation.
metrics:
$ref: '#/components/schemas/AdvancedStatsOpens'
examples:
response:
value:
- date: '2015-10-11'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-12'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-13'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-14'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-15'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-16'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-17'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-18'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-19'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-20'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-21'
stats:
- type: device
name: Webmail
metrics:
opens: 1
unique_opens: 1
- date: '2015-10-22'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-23'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-24'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-25'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-26'
stats:
- type: device
name: Webmail
metrics:
opens: 2
unique_opens: 2
- date: '2015-10-27'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-28'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-29'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-30'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-10-31'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-01'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-02'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-03'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-04'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-05'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-06'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-07'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-08'
stats:
- type: device
name: Webmail
metrics:
opens: 0
unique_opens: 0
- date: '2015-11-09'
stats:
- type: device
name: Webmail
metrics:
opens: 0
# --- truncated at 32 KB (93 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/sendgrid-stats-api-openapi.yml