Methods 

User Segment

Method Description
POST /insights/audience/segments Creates a new user segment.
GET /insights/audience/segments Paginate segments stored by customer.
GET /insights/audience/segments/:id Gets the specified (:id) user segment.
POST /insights/audience/segments/:id/ids Appends a collection of Twitter User IDs to the user segment. The user segment must be in the "appendable" state. A maximum of 100,000 IDs may be sent in a request.
DELETE /insights/audience/segments/:id Deletes the segment.

Audience

Method Description
POST /insights/audience/audiences Creates a new audience.
GET /insights/audience/audiences Paginate audiences stored by customer.
GET /insights/audience/audiences/:id Gets the audience.
DELETE /insights/audience/audiences/:id Deletes the audience.
POST /insights/audience/audiences/:id/query Retrieves aggregate insights for an audience.

Usage

Method Description
GET /insights/audience/usage Retrieves the current usage of stored segments and audiences.

Authentication 

The Audience API requires 3-legged authorization for all endpoints. Additionally, Twitter must approve your client application before you can access the API.


Rate Limits 

Rate Limiting is used to protect the system from traffic spikes and to mitigate user privacy attacks. All endpoints are rate limited based on the customer. Unless otherwise noted, all endpoints are rate limited at 10 requests per second.

For any request, the response will contain rate limiting headers as described in our Public API documentation.


POST /insights/audience/segments 

Creates a new segment. The segment will either contain a determined locked set of users by the creation metadata below, or the segment can be created in an “appendable” state, meaning Twitter user IDs can be added to it. The maximum number of user IDs within any single segment or single audience is 30 million.

HTTP Method / URI POST /insights/audience/segments
Entity User segment metadata.
  • name -- a unique name for the user segment. The name must be less than 255 characters and can contain hyphens (ASCII 45), underscores (ASCII 95), and alphanumeric characters.
  • followed -- an optional field to specify that the segment will be populated with user IDs for followers of the corresponding user ID. At this time, only one user ID may be used to construct a ‘followed’ segment.
  • impressed -- an optional field to specify that the segment will be created with users that have viewed a brand’s owned organic Tweets over the last 90 days. Notes: impressed audience segments may only be created by an account owner, or a user that has been granted access to the account. Read more about Access Control here. If a segment created via a brand’s owned, impressed audience does not contain 500 or more users, the Audience API will return an error at the time of segment creation.
  • engaged -- an optional field to specify that the segment will be created with users that have taken an engagement action (like, retweet, followed, or click) on a brand’s owned organic Tweets over the last 90 days. Notes: engaged audience segments may only be created by an account owner, or a user that has been granted access to the account. Read more about Access Control here. If a segment created via a brand’s owned, engaged audience does not contain 500 or more users, the Audience API will return an error at the time of segment creation.
  • tailored -- an optional field to specify that the segment will be created with users that included in a Tailored Audience. Note: Tailored Audience segments may only be created by the owner of the Tailored Audience, or a user that has been granted access to the account’s Tailored Audiences. Read more about Access Control here.

  • To obtain a list of Tailored Audience IDs, you must read from the Twitter Ads API -- specifically, the GET accounts/:account_id/tailored_audiences endpoint.
Response Codes See the Response Codes table.
Response Headers Location -- the URI to reference the created resource.
Example (appendable segment)
  POST /insights/audience/segments 
  HTTP/1.1
  host: data-api.twitter.com
  content-type: application/json

  {
   "name": "my-segment-name"
  }
          
  HTTP/1.1 201 CREATED

  Location: https://data-api.twitter.com/insights/audience/segments/aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111

  {
   "id": "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
   "created": "2015-08-25T05:15:59Z",
   "created_by": "987654321",
   "last_modified": "2015-08-25T05:15:59Z",
   "name": "my-segment-name",
   "num_user_ids": "0",
   "num_distinct_user_ids": "0",
   "state": "appendable",
   "audience_ids": []
  }
          
Example (followers)
  POST /insights/audience/segments 
  HTTP/1.1
  host: data-api.twitter.com
  content-type: application/json

  {
   "name": "twitter-followers-segment",
   "followed": {
      "user_ids": [
         "123456789"
      ]
    }
  }
          
    HTTP/1.1 201 CREATED

    Location: https://data-api.twitter.com/insights/audience/segments/aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111

    {
     "id": "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
     "created": "2015-08-25T05:15:59Z",
     "created_by": "987654321",
     "last_modified": "2015-08-25T05:15:59Z",
     "name": "twitter-followers-segment",
     "num_user_ids": "456654",
     "num_distinct_user_ids": "456654",
     "state": "locked",
     "audience_ids": []
    }

          
   HTTP/1.1 400 Bad Request

    {
     "errors": ["1 user(s) are unavailable."],
     "unavailable": ["1681548366"]
    }
          
Note: For all audiences and segments, num_distinct_user_ids is an estimated value. In these cases, we expect roughly 1% error from the exact values.
Example (impressed)
  POST /insights/audience/segments 
  HTTP/1.1
  host: data-api.twitter.com
  content-type: application/json

  {
   "name": "my-organic-impressed-audience-segment",
   "impressed": {
      "user_ids": [
         "123456789"
      ]
    }
  }
          
  HTTP/1.1 201 CREATED

  Location: https://data-api.twitter.com/insights/audience/segments/aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111

  {
   "id": "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
   "created": "2015-08-25T05:15:59Z",
   "created_by": "987654321",
   "last_modified": "2015-08-25T05:15:59Z",
   "name": "my-organic-impressed-audience-segment",
   "num_user_ids": "30000000",
   "num_distinct_user_ids": "30000000",
   "state": "locked",
   "audience_ids": []
  }

          
  HTTP/1.1 400 Bad Request

  {
     "errors": ["You are not authorized for 1 user(s)."],
     "unauthorized": ["987654321"]
  }
          
  HTTP/1.1 400 Bad Request

  {
     "errors": ["Organic segment size is less than the minimum audience size [500]."]
  }
          
Notes: At this time, the Audience API will not display a number of user IDs nor distinct user IDs for organic audiences. A fixed placeholder value of 30M is listed, as organic segments cannot be combined with other user segments to create a new audience. In the event that a segments created via a brand’s owned, impressed audience does not contain 500 or more users, the Audience API will return an error at the time of segment creation.
Example (engaged)
  POST /insights/audience/segments 
  HTTP/1.1
  host: data-api.twitter.com
  content-type: application/json

  {
   "name": "my-organic-engaged-audience-segment",
   "engaged": {
      "user_ids": [
         "123456789"
      ]
    }
  }
          
  HTTP/1.1 201 CREATED

  Location: 
  https://data-api.twitter.com/insights/audience/segments/aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111

  {
     "id": "c0dcdc62-e659-4578-b7fa-e8fe2da5c4c0",
     "created": "2016-07-07T00:56:15Z",
     "created_by": "987654321",
     "last_modified": "2016-07-07T00:56:15Z",
     "state": "locked",
     "name": "my-organic-engaged-audience-segment",
     "num_user_ids": "30000000",
     "num_distinct_user_ids": "30000000",
     "audience_ids": []
  }

          
  HTTP/1.1 400 Bad Request

  {
     "errors": ["You are not authorized for 1 user(s)."],
     "unauthorized": ["987654321"]
  }
          
  HTTP/1.1 400 Bad Request

  {
     "errors": ["Organic segment size is less than the minimum audience size [500]."]
  }
          
Notes: At this time, the Audience API will not display a number of user IDs nor distinct user IDs for organic audiences. A fixed placeholder value of 30M is listed, as organic segments cannot be combined with other user segments to create a new audience. In the event that a segments created via a brand’s owned, engaged audience does not contain 500 or more users, the Audience API will return an error at the time of segment creation.
Example (tailored audiences)
  POST /insights/audience/segments 
  HTTP/1.1
  host: data-api.twitter.com
  content-type: application/json

  {
   "name": "my-tailored-audience-segment",
   "tailored": tailored_audience_ids": [
            "h21y6"
          ]
  }
          
  HTTP/1.1 201 CREATED

  Location: https://data-api.twitter.com/insights/audience/segments/aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111

  {
   "id": "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
   "created": "2015-08-25T05:15:59Z",
   "created_by": "987654321",
   "last_modified": "2015-08-25T05:15:59Z",
   "name": "my-tailored-audience-segment",
   "num_user_ids": "67890",
   "num_distinct_user_ids": "67890",
   "state": "locked",
   "audience_ids": []
  }

          
   HTTP/1.1 400 Bad Request

  {
     "errors": ["You are not authorized for 1 tailored audience(s)."],
     "unauthorized": ["h21y6"]
  }
          
Notes: To obtain a list of Tailored Audience IDs, you must read from the Twitter Ads API -- specifically, the GET accounts/:account_id/tailored_audiences endpoint. All Tailored Audience IDs should be listed as Base 36 values. For all audiences and segments, num_distinct_user_ids is an estimated value. In these cases, we expect roughly 1% error from the exact values.

GET /insights/audience/segments  

Paginate segments stored by a customer, across all end users. In the below JSON, created_by indicates the end user that has created each segment.

HTTP Method / URI GET /insights/audience/segments
Response Codes See the Response Codes table.
Query Parameter next=[value] -- An initial next value of an empty string will enable pagination from the beginning. Subsequent requests should use the API provided next value from the previous request to continue pagination. A query response without a “next” field indicates completion of pagination.
Response Headers Location -- the URI to reference the created resource
Example Request (begin pagination)
GET /insights/audience/segments?next= 
HTTP/1.1
host: data-api.twitter.com
content-type: application/json
        
Example Response (begin pagination)
HTTP/1.1 200 OK

{
 "next" : "MjQxNV8yODU2MDEzMjg0XzM4IQ",
 "segments": [
  {
   "id": "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
   "created": "2015-08-25T05:15:59Z",
   "created_by": "987654321",
   "last_modified": "2015-08-25T05:15:59Z",
   "name": "my-segment-name",
   "num_user_ids": "0",
   "num_distinct_user_ids": "0",
   "state": "appendable",
   "audience_ids": []
  },
  {
   "id": "bbbbbbbb-1111-bbbb-1111-bbbb1111bbbb1111",
   "created": "2015-08-25T05:15:59Z",
   "created_by": "123456789",
   "last_modified": "2015-08-25T05:15:59Z",
   "name": "my-segment-name",
   "num_user_ids": "10000000",
   "num_distinct_user_ids": "10000000",
   "state": "locked",
   "audience_ids": [
    "cccccccc-1111-cccc-1111-cccc1111cccc1111"
   ]
  }
 ]
}
        
Example Request (pagination)
GET /insights/audience/segments?next=MjQxNV8yODU2MDEzMjg0XzM4IQ 
HTTP/1.1
host: data-api.twitter.com
content-type: application/json
        
Example Response (pagination)
HTTP/1.1 200 OK

{
 "segments": []
} 
        

GET /insights/audience/segments/:id  

Gets the user segment.

HTTP Method / URI GET /insights/audience/segments/:id
URI Params id -- the user segment identifier
Response Codes See the Response Codes table.
Example Request
GET /insights/audience/segments/aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111 
HTTP/1.1
host: data-api.twitter.com
content-type: application/json
          
Example Response
HTTP/1.1 200 OK

{
 "id": "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
 "created": "2015-08-25T05:15:59Z",
 "created_by": "987654321",
 "last_modified": "2015-08-25T05:15:59Z",
 "name": "my-segment-name",
 "num_user_ids": "0",
 "num_distinct_user_ids": "0",
 "state": "appendable",
 "audience_ids": []
}
          

POST /insights/audience/segments/:id/ids 

Adds a collection of Twitter User IDs to the user segment. The user segment must be in the “appendable” state. A maximum of 100,000 IDs may be sent in a request.

IDs should not be added to a user segment concurrently. If concurrent requests attempt to add users to the same user segment, then some of the requests may fail.

HTTP Method / URI POST /insights/audience/segments/:id/ids
URI Params id -- the user segment identifier
Response Codes See the Response Codes table.
Example Request
POST /insights/audience/segments/aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111/ids 
HTTP/1.1
host: data-api.twitter.com
content-type: application/json

{
 "user_ids": [
  "123456789", 
  "234567891"
 ]
}
          
Example Response
HTTP/1.1 200 OK

{
 "id": "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
 "created": "2015-08-25T05:15:59Z",
 "created_by": "987654321",
 "last_modified": "2015-08-30T05:15:59Z",
 "name": "my-segment-name",
 "num_user_ids": "12345678",
 "num_distinct_user_ids": "12345678",
 "state": "appendable",
 "audience_ids": []
}
          

DELETE /insights/audience/segments/:id 

Deletes the segment. An existing audience that references the deleted segment remains unchanged and may continued to be queried.

HTTP Method / URI DELETE /insights/audience/segments/:id
URI Params id -- the user segment identifier
Response Codes See the Response Codes table.
Example Request
DELETE /insights/audience/segments/aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111 
HTTP/1.1
host: data-api.twitter.com
content-type: application/json
          
Example Response
HTTP/1.1 200 Ok
          

POST /insights/audience/audiences 

Creates a new audience. Segments referenced by the audience are moved to the “locked” state. Twitter user IDs cannot be appended to locked segments. The number of distinct user IDs in the audience must be at least 500 and the total number of user IDs must be no more than 30 million. Each customer may store a maximum of 100,000 audiences at any time. The maximum number of user IDs within any single segment or single audience is 30 million.

HTTP Method / URI POST /insights/audience/audiences
Entity Audience metadata.
  • name -- a unique name for the audience. The name must be less than 255 characters and can contain hyphens (ASCII 45), underscores (ASCII 95), and alphanumeric characters.
URI Params id -- the user segment identifier
Response Codes See the Response Codes table.
Response Headers Location -- the URI to reference the created resource
Example Request
POST /insights/audience/audiences 
HTTP/1.1
host: data-api.twitter.com
content-type: application/json

{
 "name": "my-audience-name",
 "segment_ids": [
  "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
  "bbbbbbbb-1111-bbbb-1111-bbbb1111bbbb1111"
 ] 
}
          
Example Response
HTTP/1.1 201 CREATED

Location: https://data-api.twitter.com/insights/audience/audiences/cccccccc-1111-cccc-1111-cccc1111cccc1111

{
  "id": "cccccccc-1111-cccc-1111-cccc1111cccc1111",
  "name": "1440483707107",
  "created": "2015-08-25T06:21:47Z",
  "created_by": "987654321",
  "last_modified": "2015-08-25T06:21:47Z",
  "num_user_ids": "500000",
  "num_distinct_user_ids": "500000",
  "state": "available",
  "segment_ids": [
   "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
   "bbbbbbbb-1111-bbbb-1111-bbbb1111bbbb1111"
  ]
}
          

GET /insights/audience/audiences?next=[value] 

Paginate audiences stored by a customer, across all end users. In the below JSON, created_by indicates the end user that has created each audience.

HTTP Method / URI GET /insights/audience/audiences
Query Parameter next=[value] -- An initial next value of an empty string will enable pagination from the beginning. Subsequent requests should use the API provided next value from the previous request to continue pagination. A query response without a “next” field indicates completion of pagination.
Response Codes See the Response Codes table.
Example Request (begin pagination)
GET /insights/audience/audiences?next= HTTP/1.1
host: data-api.twitter.com
content-type: application/json
        
Example Response (begin pagination)
HTTP/1.1 200 OK

{
 "next" : "MjQxNV8yODU2MDEzMjg0XzM4IQ",
 "audiences": [
  {
   "id": "cccccccc-1111-cccc-1111-cccc1111cccc1111",
   "name": "1440483707107",
   "created": "2015-08-25T06:21:47Z",
   "created_by": "987654321",
   "last_modified": "2015-08-25T06:21:47Z",
   "num_user_ids": "500000",
   "num_distinct_user_ids": "500000",
   "state": "available",
   "segment_ids": [
    "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
    "bbbbbbbb-1111-bbbb-1111-bbbb1111bbbb1111"
   ]
  }
 ]
}
        
Example Request (pagination)
GET /insights/audience/audiences?next=MjQxNV8yODU2MDEzMjg0XzM4IQ 
HTTP/1.1
host: data-api.twitter.com
content-type: application/json
        
Example Response (pagination)
HTTP/1.1 200 OK

{
 "audiences": []
} 
        

GET /insights/audience/audiences/:id 

Gets the audience.

HTTP Method / URI GET /insights/audience/audiences/:id
URI Params id -- the audience identifier
Response Codes See the Response Codes table.
Example Request
GET /insights/audience/audiences/cccccccc-1111-cccc-1111-cccc1111cccc1111 
HTTP/1.1
host: data-api.twitter.com
content-type: application/json
          
Example Response
HTTP/1.1 200 OK

{
  "id": "cccccccc-1111-cccc-1111-cccc1111cccc1111",
  "name": "1440483707107",
  "created": "2015-08-25T06:21:47Z",
  "created_by": "987654321",
  "last_modified": "2015-08-25T06:21:47Z",
  "num_user_ids": "500000",
  "num_distinct_user_ids": "500000",
  "state": "available",
  "segment_ids": [
   "aaaaaaaa-1111-aaaa-1111-aaaa1111aaaa1111",
   "bbbbbbbb-1111-bbbb-1111-bbbb1111bbbb1111"
  ]
}
          

DELETE /insights/audience/audiences/:id 

Deletes the audience. User segments referenced by the audience remain unchanged and may continue to be used in existing and new audiences.

HTTP Method / URI DELETE /insights/audience/audiences/:id
URI Params id -- the audience identifier
Response Codes See the Response Codes table.
Example Request
DELETE /insights/audience/audiences/cccccccc-1111-cccc-1111-cccc1111cccc1111 HTTP/1.1
host: data-api.twitter.com
content-type: application/json
          
Example Response
HTTP/1.1 200 Ok
          

POST /insights/audience/audiences/:id/query 

Retrieves aggregate insights for an audience.

HTTP Method / URI POST /insights/audience/audiences/:id/query
Entity

An audience query. The query is composed of one or more groupings (i.e., how to organize the results), with a maximum of 10 groupings per query.

Each grouping must be given a unique name relative to the query (e.g., ‘my-grouping’, ‘my-grouping-2’ in the below example). The grouping name must also be less than 255 characters and can contain hyphens (ASCII 45), underscores (ASCII 95), and alphanumeric characters.

A grouping is composed of one or more group-bys, with a maximum of 2 group-bys (e.g., user.device.network by user.location.country).

Supported group-bys are:

  • user.age
  • user.device.network
  • user.device.os
  • user.gender
  • user.interest
  • user.language
  • user.location.country
  • user.location.metro
  • user.location.region
  • user.tv.genre
  • user.tv.show

See the Demographic Definitions section for more details.

Notes:
  • Although the Audience API returns aggregate insights about an audience, results do not include insights about any user with a protected (private) Twitter account.
  • In cases where it is not possible to return insights for a query grouping due to our user privacy reporting thresholds (fewer than 75 users within a requested demographic grouping), you will receive the message,“Unable to return insights due to reporting threshold.” in place of the results for the grouping.
  • Audience API groupings are evaluated independant of each other. As such, each grouping will either yield insights or its own error message.
Response Codes See the Response Codes table.
Example Request
POST /insights/audience/audiences/cccccccc-1111-cccc-1111-cccc1111cccc1111/query HTTP/1.1
host: data-api.twitter.com
content-type: application/json

{
 "groupings": {
  "my-grouping-1": {
   "group_by": [
    "user.gender",
    "user.tv.genre"
   ]
  },
  "my-grouping-2": {
   "group_by": [
    "user.language"
   ]
  },
  "my-grouping-3": {
   "group_by": [
    "user.location.metro"
   ]
  }
 }
}
          
Example Response
HTTP/1.1 200 OK

{
 "groupings": { 
  "my-grouping-1": {
   "Male": {
    "Comedy": "60.31",
    "Drama": "39.29"
   },
   "Female": {
    "Drama": "65.89",
    "Soap Opera: "34.11"
   }
  },
  "my-grouping-2": {
   "English": "59.83"
  },
  "my-grouping-3" : {
    "errors" : [
      "Unable to return insights due to reporting thresholds."
    ]
  }
 }
}
          

GET /insights/audience/usage 

Retrieves the current usage for the customer. Segment and audience usage is shown as a limit and a remaining amount that can be created. We encourage customers to monitor their own monthly query limits to ensure they stay within their monthly allocations.

HTTP Method / URI GET /insights/audience/usage
Response Codes See the Response Codes table.
Example Request
GET /insights/audience/usage HTTP/1.1
host: data-api.twitter.com
content-type: application/json
          
Example Response
HTTP/1.1 200 OK

{
 "segments_limit_limit": "50000",
 "segments_limit_remaining": "47050",
 "audiences_limit_limit": "100000",
 "audiences_limit_remaining": "32756"
}
          

Response Codes 

Status Text Description
200 OK The request was successful.
400 Bad Request Generally, this response occurs due to the presence of invalid JSON in the request, or where the request failed to send any JSON payload.
401 Unauthorized HTTP authentication failed due to invalid credentials. Check your OAuth keys and tokens.
404 Not Found The resource was not found at the URL to which the request was sent, likely because an incorrect URL was used.
429 Too Many Requests Your app has exceeded the limit on API requests.
500 Internal Server Error There was an error on Gnip's side. Retry your request using an exponential backoff pattern.
502 Proxy Error There was an error on Gnip's side. Retry your request using an exponential backoff pattern.
503 Service Unavailable There was an error on Gnip's side. Retry your request using an exponential backoff pattern.


Continue to the Interpreting Insights page