GET /pylon/{service}/task/{type}

Retrieve your PYLON tasks.

An HTTPS GET request sent to:

https://api.datasift.com/v1.5/pylon/{service}/task/{type}

A successful call to this endpoint returns: 200 OK plus a JSON object.

Parameters

Parameter Description
service
required

The service to which the task relates.

Example value: linkedin

type
required

The type of the task.

For PYLON analysis tasks analysis.
For Media Strategy API tasks strategy.

status
optional

Filter tasks based on their current status.

Example value: completed

page
optional

The page you want to retrieve. For example, if you set this parameter to 3, the API will return page 3 only (if there is sufficient data to fill more than 2 pages).

Default: 1

per_page
optional

Number of results to return per page.

Default: 25
Maximum: 100

Examples

  1. Retrieve your most recently created analysis tasks.

    This call will return your most recently created tasks (up to 25 as this is the default page size).

    curl -X GET 'https://api.datasift.com/v1.5/pylon/linkedin/task/analysis' \
      -H 'Authorization: username:identity_api_key'

  2. Retrieve your most recently created Media Strategy API tasks.

    This call will return your most recently created tasks (up to 25 as this is the default page size).

    curl -X GET 'https://api.datasift.com/v1.5/pylon/linkedin/task/strategy' \
      -H 'Authorization: username:identity_api_key'

  3. Retrieve page 2 of your PYLON analysis tasks, where 10 tasks are included per page.

    curl -X GET 'https://api.datasift.com/v1.5/pylon/linkedin/task/analysis?page=2&per_page=10' \
      -H 'Authorization: username:identity_api_key'

  4. Retrieve a list of your PYLON analysis tasks currently in a "queued" state.

    curl -X GET 'https://api.datasift.com/v1.5/pylon/linkedin/task/analysis?status=queued' \
      -H 'Authorization: username:identity_api_key'

Output

The output looks like this:

HTTP/1.1 200 OK
{
  "count": 15,
  "page": 1,
  "pages": 2,
  "per_page": 10,
  "tasks": [
    {
      "id": "f3756f8de519cbd7449b8780e7eaffd407eb7f00",
      "identity_id": "03a78e036afb076a6606c5195c1f9b42",
      "subscription_id": "e9dde04774540ac119c2317a4d15a8b3a1350937",
      "name": "Example task",
      "type": "analysis",
      "parameters": {...}
      },
      "usage": {
        "analysis_tasks": 1
      },
      "steps_completed": 1,
      "total_steps": 1,
      "message": null,
      "result": null,
      "status": "completed",
      "created_at": 1467389452,
      "updated_at": 1467389460
    },
        ...
    ]
}

The fields in the output are as follows:

Property Type Description
count int If no status filter has been applied, the total number of tasks for the user. If a status filter has been applied, the total number of tasks that match the status requested.
page int The page number of the result.
per_page int The number of tasks per page of results.
tasks array(objects) The list of tasks on the current page of results.
id string Id of the task. A 40-character alphanumeric hash.
identity_id string The id of the identity that submitted the task.
subscription_id string The id of the index the task was run against.
name string The name the task was given when it was submitted.
type string The type of the task.
parameters object The parameters supplied when the task was submitted.
usage object Relevant only for strategy tasks, this property tells you the usage incurred by running the task stated as a number of analysis tasks.
steps_completed int Relevant only for strategy tasks, this property tells you how many steps of the task have been completed so far.
total_steps int Relevant only for strategy tasks, this property tells you how many steps are required to complete the task.
message string If the task fails, an error message giving details of the failure.
status string

The status of the task, one of:

  • queued - the task is waiting to be processed
  • running - the task is currently being processed
  • completed - the task has been processed successfully
  • failed - the task failed during processing
created_at int Unix timestamp stating when the task was submitted.
updated_at int Unix timestamp stating when the task was last updated.

Responses

Response code Description
Status 200 OK The call was successful.
Status 400 Bad Request

One or more of the passed parameters was invalid. For example:

{
    "error": "The page parameter must be an integer greater than zero"
}
{
    "error": "The per_page parameter must be an integer greater than zero and less or equal to 100"
}

Notes

  1. All calls to the API must be properly authenticated with a DataSift username and API key.
  2. All calls to the API must be versioned.

Resource information

Rate limit cost: 5

Requires authentication: Yes

Response formats: JSON, JSONP