Sorting

Overview

Sorting is available for most Ads API collection endpoints (that return a list of objects). Depending on the endpoint, you will find various parameters enabled for sorting. Most fields returned by these parameters (except for IDs and ENUMs) will be sortable.

API Collection Sortable Parameters
Accounts created_at, updated_at, deleted, name
Funding Instruments created_at, updated_at, deleted, funded_amount_local_micro, start_time, end_time
Campaigns created_at, updated_at, deleted, name, start_time, end_time, daily_budget_amount_local_micro, total_budget_amount_local_micro, standard_delivery
Line Items created_at, updated_at, deleted, bid_amount_local_micro
Cards created_at, updated_at, deleted, name
Promoted Accounts created_at, updated_at, deleted, paused
Promoted Tweets created_at, updated_at, deleted, paused
App Event Tags created_at, updated_at, deleted, post_view_attribution_window, post_engagement_attribution_window, assisted_conversion, provider_app_event_name

Getting Started

In your API request simply append sort_by=[attribute name]-[asc/desc] where the attribute is a valid attribute that is returned in the JSON of your GET request.

For example, you can use ?name-asc to sort by name alphabetically or ?name-desc to sort in reverse.

Going Deeper

Below is a sample API request to return all line items by the bid_amount_local_micro in descending order:

$ twurl -H ads-api.twitter.com "/1/accounts/k9w0oe/line_items?sort_by=bid_amount_local_micro-desc"

{
  "request": {
    "params": {
      "sort_by": [
        "bid_amount_local_micro-desc"
      ],
      "account_id": "k9w0oe"
    }
  },
  "data": [
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 3000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1iw6k",
      "paused": true,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-09T02:11:32Z",
      "updated_at": "2015-05-27T23:01:45Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1kv71",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 3000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "FOLLOW",
      "product_type": "PROMOTED_ACCOUNT",
      "bid_unit": "FOLLOW",
      "total_budget_amount_local_micro": null,
      "objective": "FOLLOWERS",
      "id": "1nlqp",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-10-20T18:57:18Z",
      "updated_at": "2014-10-20T18:57:18Z",
      "include_sentiment": null,
      "campaign_id": "1pjkp",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 2500000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1iw6l",
      "paused": true,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-09T02:11:54Z",
      "updated_at": "2014-09-17T06:23:23Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1kv71",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 2500000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1iw9q",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-09T03:11:46Z",
      "updated_at": "2014-09-09T03:26:17Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1kv71",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 2500000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1iw9r",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-09T03:12:02Z",
      "updated_at": "2014-09-09T03:30:44Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1kv71",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "TWITTER_TIMELINE",
        "TWITTER_PROFILE"
      ],
      "bid_amount_local_micro": 2000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1kkze",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-24T01:18:20Z",
      "updated_at": "2015-08-30T04:41:34Z",
      "include_sentiment": null,
      "campaign_id": "1mj4h",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "TWITTER_TIMELINE",
        "TWITTER_PROFILE"
      ],
      "bid_amount_local_micro": 2000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1kkzk",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-24T01:23:06Z",
      "updated_at": "2015-08-30T04:41:34Z",
      "include_sentiment": null,
      "campaign_id": "1mj4n",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 2000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1kkzq",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-24T01:25:06Z",
      "updated_at": "2014-09-24T01:34:20Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1mj48",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 2000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": null,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1kkzr",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-24T01:25:09Z",
      "updated_at": "2014-09-24T01:34:41Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1mj48",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 2000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": 6000000,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1kl0e",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-24T01:42:49Z",
      "updated_at": "2014-09-24T01:51:25Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1mj57",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 2000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": 12000000,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1kl0g",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-24T01:43:19Z",
      "updated_at": "2014-09-24T01:51:40Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1mj57",
      "creative_source": "MANUAL",
      "deleted": false
    },
    {
      "bid_type": "MAX",
      "name": "Untitled",
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 2000000,
      "automatically_select_bid": false,
      "advertiser_domain": null,
      "primary_web_event_tag": null,
      "charge_by": "ENGAGEMENT",
      "product_type": "PROMOTED_TWEETS",
      "bid_unit": "ENGAGEMENT",
      "total_budget_amount_local_micro": 6000000,
      "objective": "TWEET_ENGAGEMENTS",
      "id": "1kl0l",
      "paused": false,
      "account_id": "k9w0oe",
      "optimization": "DEFAULT",
      "categories": [

      ],
      "currency": "USD",
      "created_at": "2014-09-24T01:45:09Z",
      "updated_at": "2014-09-24T01:51:54Z",
      "include_sentiment": "POSITIVE_ONLY",
      "campaign_id": "1mj5d",
      "creative_source": "MANUAL",
      "deleted": false
    }
  ],
  "data_type": "line_item",
  "total_count": 12,
  "next_cursor": null
}