Developer Guide: Getting Task Results

In this guide you'll learn how to access the results of tasks submitted to the Media Strategies API.

Retrieving task results

If an analysis task is complete, calling the GET /pylon/{service}/task/{type}/{id} endpoint returns the task along with its analysis results.

For example to retrieve results for a strategy task with the id b39746f8b4837623b528c793ef7fb84b61998ddd, we would make the following API call:

GET /pylon/linkedin/task/strategy/b39746f8b4837623b528c793ef7fb84b61998ddd

The response from the API will have the form:

{
  "id": "b39746f8b4837623b528c793ef7fb84b61998ddd",
  "identity_id": "06b09175dd1b3b724530c50187c84f25",
  "subscription_id": "cd99abbc812f646c77bfd8ddf767a134f0b91e84",
  "name": "Top urls for cloud",
  "type": "strategy",
  "parameters": { ... },
  "result": { ... },
  "usage": {
    "analysis_tasks": 3
  },
  "steps_completed": 3,
  "total_steps": 3,
  "message": "",
  "status": "completed",
  "created_at": 1493740057,
  "updated_at": 1493740077
}

Reading task results

In the example above, we ran a top_urls strategy. In this case, the results object of the completed strategy task will take the following form:

{
  ...
  "result": {
    "interactions": 4133100,
    "redacted": false,
    "unique_authors": 3929200,
    "urls": [
      {
        "engagement_ratio": 1.1,
        "interactions": 30100,
        "url": "https://www.example.com",
        "unique_authors": 19800
      },
      {
        "engagement_ratio": 1,
        "interactions": 29200,
        "url": "https://www.example.com/blog",
        "unique_authors": 18200
      },
      ...
    ]
  }
}

The exact structure of the JSON contained in the results object will change depending on your chosen strategy. You can find details of the output for each strategy within the strategies documentation pages.

In this case the top_urls strategy returns the top urls as engaged with by the analyzed audience. The urls are listed within the urls property each with the amount of engagement they received.

Redacted results

All strategies will tell you if the analysis could not be completed due to insufficient data.

This is called a 'redacted' result and will be shown using the redacted property:

{
  ...
  "result": {
    "redacted": true
  }
}

If you receive a redacted result for a strategy task you should consider changing your parameters to analyze a larger audience or broader topic.