Returning DRAFT campaigns by default for v2?

[emilyb]

for version 2 of the api, I’m receiving inconsistent results from the API. This afternoon, I was able to make a call to the API campaign endpoint scoped to a specific campaign that has a status of DRAFT. Now I make the same call and no data is returned, although if I include the param DRAFT_ONLY, that campaign is again being returned.

What is the default behavior for both making a call to retrieve all campaigns and scoped to a specific id.

[juanshishido]

@emilyb: If you’re seeing different results with the exact same request, please provide some examples so we can try to reproduce the issue.

While we wait for that information, let me provide some information on retrieving draft campaigns. The draft_only parameter is only accepted in some our index endpoints, such as GET accounts/:account_id/campaigns. Index endpoints allow users to retrieve some or all entities associated with the account specified in the resource path. In contrast, we provide show endpoints, such as GET accounts/:account_id/campaigns/:campaign_id, that allow users to retrieve specific entities. These endpoints do not accept the draft_only parameter. You can tell the difference between the two type of endpoints by looking at the data attribute. In index responses, data will be an array. In show responses, data will be an object.

Let’s look at a quick example. Campaign 9asbs is a draft campaign. When I make an index request without specifying draft only, I get an empty data array, as expected, because we did not specify draft_only=true:

$ twurl -H ads-api.twitter.com "/2/accounts/18ce54d4x5t/campaigns?campaign_ids=9asbs"
{
  "request": {
    "params": {
      "campaign_ids": [
        "9asbs"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": []
}

With draft only specified:

$ twurl -H ads-api.twitter.com "/2/accounts/18ce54d4x5t/campaigns?campaign_ids=9asbs&draft_only=true"
{
  "request": {
    "params": {
      "campaign_ids": [
        "9asbs"
      ],
      "account_id": "18ce54d4x5t",
      "draft_only": true
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "draft campaign",
      "start_time": "2017-08-17T16:49:00Z",
      "reasons_not_servable": [
        "DRAFT"
      ],
      "servable": false,
      "daily_budget_amount_local_micro": 1000000,
      "end_time": null,
      "funding_instrument_id": "lygyi",
      "duration_in_days": null,
      "standard_delivery": true,
      "total_budget_amount_local_micro": 1000000,
      "id": "9asbs",
      "entity_status": "DRAFT",
      "account_id": "18ce54d4x5t",
      "frequency_cap": null,
      "currency": "USD",
      "created_at": "2017-08-17T16:49:32Z",
      "updated_at": "2017-08-17T16:49:32Z",
      "deleted": false
    }
  ]
}

Finally, the show request, which does not need (or accept) draft_only:

$ twurl -H ads-api.twitter.com "/2/accounts/18ce54d4x5t/campaigns/9asbs"
{
  "request": {
    "params": {
      "campaign_id": "9asbs",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "draft campaign",
    "start_time": "2017-08-17T16:49:00Z",
    "reasons_not_servable": [
      "DRAFT"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": 1000000,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "duration_in_days": null,
    "standard_delivery": true,
    "total_budget_amount_local_micro": 1000000,
    "id": "9asbs",
    "entity_status": "DRAFT",
    "account_id": "18ce54d4x5t",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2017-08-17T16:49:32Z",
    "updated_at": "2017-08-17T16:49:32Z",
    "deleted": false
  }
}

Hope this helps clarify. Will keep an eye out for your response.

[emilyb]

Hi Juan
Thanks for the reply.

now that you mention it, when a response was returned for a draft campaign, it might have been using a show endpoint. I honestly can’t remember and was trying a number of things.
Your reply answered my question though, making an index request without specifying draft_only=true will not return draft campaigns. If I may offer some feedback, I personally find draft_only as misleading. To me having draft_only=false would signify a response including both draft campaigns and paused/active ones. Would help if the documentation was updated to clarify what draft_only means.

Thanks

[juanshishido]

Thanks for confirming, @emilyb, and for asking the question. If any behavior or functionality seems off, we appreciate hearing it.

Thanks for the feedback, too. The goal with the parameter naming was to distinguish it from something like with_deleted, which, when true, acts as you describe—includes both deleted and non-deleted entities. With draft_only, we are trying to convey that the response will only include draft entities, with the converse indicating we won’t return any draft entities. I can see how it would be confusing in the false case, though. In the documentation, the description states, “Scope the response to just draft campaigns.” Would it help if we clarified the behavior in the true and false conditions?

Thanks again!