Table of contents

Activity API

The Activity API allows you to view details about a specific harvesting job. This endpoint allows you to find extractor errors, and items that had a specific error message.

List Extractor Errors

This API will show you the amount of errors each extractor had.

GET /api/data/v3/activity/request/{request_id}/extractors
  • {request_id} - (string) Harvest Job request ID

You will receive the following response:

{
	"extractors": [{
			"name": "captions",
			"display_name": "Embedded Captions",
			"num_errors": 0
		},
		{
			"name": "document_pages",
			"display_name": "Documents",
			"num_errors": 0
		},
		{
			"name": "drm",
			"display_name": "DRM",
			"num_errors": 2
		},
		{
			"name": "exiv2",
			"display_name": "EXIV2",
			"num_errors": 0
		}
	]
}
  • extractors[].name - (string) The actual name of the extractor that ran in this harvest. This value is used as {extractor} in all other Activity endpoint API requests.
  • extractors[].display_name - (string) The display name of the extractor that ran in this harvest
  • extractors[].num_error - (integer) Amount of errors the extractor caught

List Errors for an Extractor

This API will list all errors that occurred in this harvesting job. Each error will have an error_hash that will allow you to find items in the next API endpoint.

GET /api/data/v3/activity/request/{request_id}/extractors/{extractor}?page_token={token}&limit={limit}&offset={offset}
  • {request_id} - (string) Harvest Job request ID
  • {extractor} - (string) Extractor name
Optional Queries
  • limit - (integer) Maximum results to show
  • offset - (integer) The offset amount of results (used for pagination)
  • page-token - (string) Show results for the next set of results, from next_page_token value.

You will receive the following response:

{
	"extractor": "credits",
	"extractor_name": "Credits",
	"errors": [{
		"error": "credits: error message ouchhh",
		"error_hash": "8f1e07deac51451cc1ed2778312af796",
		"num_files": 1
	}],
	"next_page_token": "",
	"previous_page_token": ""
}
  • extractor - (string) The actual name of the extractor being searched
  • extractor_name - (string) The display name of the extractor being searched
  • errors[].error - (string) The error message that occured
  • errors[].error_hash - (string) The MD5 hash of the error message
  • errors[].num_files - (integer) Amount of errors with same error message
  • num_files - (integer) Total amount of files that had errors with extractor
  • next_page_token - (string) The next set of paginated results for page-token query
  • previous_page_token - (string) The previous set of paginated results for page-token query

The previous and next page tokens can be used to retrieve the previous or next page of results. If the previous or next page tokens are an empty string, then there are no more results. Use the previous_page_token or next_page_token as the URL query string value for page-token to fetch previous/next set of results.

List Items That Have a Specific Error

This API will list all item’s in the harvesting job that had this specific error message. The error_md5 is a MD5 hash of the error message string.

GET /api/data/v3/activity/request/{request_id}/extractors/{extractor}/errors/{error_md5}/files?page_token={token}&limit={limit}&offset={offset}
  • {request_id} - (string) Harvest Job request ID
  • {extractor} - (string) Extractor name
  • {error_md5} - (string) Error message hashed into MD5.
Optional Queries
  • limit - (integer) Maximum results to show
  • offset - (integer) The offset amount of results (used for pagination)
  • page-token - (string) Show results for the next set of results, from next_page_token value.

You will receive the following response:

{
    "files": [
        {
            "item_id": "a517fe747f698e1a62d382a4addbc825",
            "name": "smpte-color-bars.mp4"
        }
    ],
    "num_files": 1,
    "next_page_token": "",
    "previous_page_token": ""
}
  • files[].item_id - (string) The Item ID that had this extractor error
  • files[].name - (string) full name of the item.
  • num_files - (integer) Total amount of files that had errors with extractor
  • next_page_token - (string) The next set of paginated results for page-token query
  • previous_page_token - (string) The previous set of paginated results for page-token query

The previous and next page tokens can be used to retrieve the previous or next page of results. If the previous or next page tokens are an empty string, then there are no more results. Use the previous_page_token or next_page_token as the URL query string value for page-token to fetch previous/next set of results.

List Multiple Extractor Errors

This API will return extractor errors for all of the request ID’s you send as a JSON array of strings.

POST /api/data/v3/activity/bulk/extractors

{"jobs": ["{request_id}", "{request_id}"]}
  • jobs - (string) The JSON object that contains an array of request_id’s.
  • request_id[] - (string) The request ID for a specific job

You will receive the following response in the same order as your array of request ID’s:

[
	{
		"request_id": "5dfd2a32e285d27ed8f17d46f29869d2",
		"extractors": [
			{
				"name": "black_scenes",
				"display_name": "Black Frames",
				"num_errors": 0
			},
			{
				"name": "drm",
				"display_name": "DRM",
				"num_errors": 0
			},
			{
				"name": "exiv2",
				"display_name": "EXIV2",
				"num_errors": 0
			},
			{
				"name": "hashes",
				"display_name": "Hashes",
				"num_errors": 0
			}
		]
	},
	{
		"request_id": "5dfd1289dc77d22895667329961ceece",
		"extractors": [
			{
				"name": "drm",
				"display_name": "DRM",
				"num_errors": 0
			},
			{
				"name": "exiv2",
				"display_name": "EXIV2",
				"num_errors": 0
			},
			{
				"name": "hashes",
				"display_name": "Hashes",
				"num_errors": 0
			}
		]
	}
]
  • request_id - (string) The request ID for this object
  • extractors[].name - (string) The actual name of the extractor that ran in this harvest. This value is used as {extractor} in all other Activity endpoint API requests.
  • extractors[].display_name - (string) The display name of the extractor that ran in this harvest
  • extractors[].num_error - (integer) Amount of errors the extractor caught

List Items harvested for a specific request

This API will show you all the items associated with request.

GET /api/data/v3/activity/request/{request_id}/items?limit={limit}&page-token={page_token}
  • {request_id} - (string) Harvest Job request ID
  • {limit} - (int) Limit the number of results. Default: 10 Max: 1000
  • {page-token} - Token specifying results page (for multi-page results).

You will receive the following response:

{
    "files": [
        {
            "item_id": "a517fe747f698e1a62d382a4addbc825",
            "name": "smpte-color-bars.mp4"
        }
    ],
    "num_files": 1,
    "next_page_token": "",
    "previous_page_token": ""
}
  • files[].item_id - (string) item_id in process by request ID.
  • files[].name - (string) full name of the item.
  • num_files - (int) Total amount of files that had errors with extractor
  • next_page_token - (string) The next set of paginated results for page-token query
  • previous_page_token - (string) The previous set of paginated results for page-token query

List Job for a specific item

This API will search all job_id in the activity index for a specific item_id and return the jobstatus for those job_ids

GET /api/data/v3/activity/item/{item_id}?limit={limit}&page-token={page_token}
  • {item_id} - (string) The Item ID to search for
  • {limit} - (int) Limit the number of results. Default: 10 Max: 100
  • {page-token} - Token specifying results page (for multi-page results).
{
    "jobs": [
        {
            "request_id": "5f69073f7a855cc76574acc96e105667",
            "container_id": "1ebc9ff9b9310d8ea5fe259b96a9fe38",
            "user_id": "5f69032a319d4f3aeb580c2946e3d1de",
            "walked_count": 1,
            "indexed_count": 1,
            "created": "2020-09-21T20:04:15.126019Z",
            "updated": "2020-09-21T20:05:00.495541Z",
            "job_type": "harvest",
            "cancelled": false,
            "walk_complete": true,
            "error_count": 1
        }
    ],
    "num_jobs": 1,
    "next_page_token": "",
    "previous_page_token": ""
}
  • num_job - (int) Total amount of job found for that item_id
  • next_page_token - (string) The next set of paginated results for page-token query
  • previous_page_token - (string) The previous set of paginated results for page-token query

Get all activity for an item_id and request_id

This API will return all the activity for a specific item id and request id.

GET /api/data/v3/activity/item/{item_id}/{request_id}?limit={limit}&page-token={page_token}
  • {item_id} - (string) The Item ID to search for
  • {request_id} - (string) The Request ID to search for
  • {limit} - (int) Limit the number of results. Default: 10 Max: 100
  • {page-token} - Token specifying results page (for multi-page results).
{
    "activities": [
        {
            "ts": "2020-09-21T22:34:41.4519053Z",
            "kind": "harvestend",
            "request_id": "5f692a73b7872fa794f7c1f0159663f1",
            "location_id": "5f690733ea16ebd7e6de5f7cee8c5199",
            "container_id": "/data/files/colorbars",
            "harvest_id": "harvest:development:5f692a8155c9bc800ba794e54a91aceb",
            "profile_id": "default",
            "extractors": [
                "audioinfo"
            ],
            "name": "smpte-color-bars.mp4",
            "source": "harvest",
            "item_id": "a517fe747f698e1a62d382a4addbc825",
            "count": 0,
            "bytes": 44909,
            "error": "",
            "error_hash": "",
            "duration": 97970200
        },
        {
            "ts": "2020-09-21T22:34:41.4126822Z",
            "kind": "extractor",
            "request_id": "5f692a73b7872fa794f7c1f0159663f1",
            "location_id": "5f690733ea16ebd7e6de5f7cee8c5199",
            "container_id": "/data/files/colorbars",
            "harvest_id": "harvest:development:5f692a8155c9bc800ba794e54a91aceb",
            "profile_id": "default",
            "extractors": [],
            "name": "smpte-color-bars.mp4",
            "source": "audioinfo",
            "item_id": "a517fe747f698e1a62d382a4addbc825",
            "count": 0,
            "bytes": 44909,
            "error": "audioinfo: no audio",
            "error_hash": "6199cf359b32392d186f07f7756e165c",
            "duration": 5820100
        },
        {
            "ts": "2020-09-21T22:34:41.3775794Z",
            "kind": "harvestdownload",
            "request_id": "5f692a73b7872fa794f7c1f0159663f1",
            "location_id": "5f690733ea16ebd7e6de5f7cee8c5199",
            "container_id": "/data/files/colorbars",
            "harvest_id": "harvest:development:5f692a8155c9bc800ba794e54a91aceb",
            "profile_id": "default",
            "extractors": [
                "audioinfo"
            ],
            "name": "smpte-color-bars.mp4",
            "source": "harvest",
            "item_id": "a517fe747f698e1a62d382a4addbc825",
            "count": 0,
            "bytes": 44909,
            "error": "",
            "error_hash": "",
            "duration": 23643900
        },
        {
            "ts": "2020-09-21T22:34:27.5080515Z",
            "kind": "walk",
            "request_id": "5f692a73b7872fa794f7c1f0159663f1",
            "location_id": "5f690733ea16ebd7e6de5f7cee8c5199",
            "container_id": "/data/files/colorbars",
            "harvest_id": "",
            "profile_id": "default",
            "extractors": [
                "audioinfo"
            ],
            "name": "smpte-color-bars.mp4",
            "source": "walkd",
            "item_id": "a517fe747f698e1a62d382a4addbc825",
            "count": 0,
            "bytes": 44909,
            "error": "",
            "error_hash": "",
            "duration": 0
        }
    ],
    "num_activities": 4,
    "next_page_token": "",
    "previous_page_token": ""
}
  • num_activities - (int) Total amount of activities found for that item_id and request_id
  • next_page_token - (string) The next set of paginated results for page-token query
  • previous_page_token - (string) The previous set of paginated results for page-token query

List Extractor Errors for a specific item

This API will show you the amount of errors each extractor had for a specific item.

GET /api/data/v3/activity/item/{item_id}/{request_id}/extractors
  • {item_id} - (string) The Item ID
  • {request_id} - (string) Harvest Job request ID

You will receive the following response:

{
	"extractors": [{
			"name": "captions",
			"display_name": "Embedded Captions",
			"num_errors": 0
		},
		{
			"name": "document_pages",
			"display_name": "Documents",
			"num_errors": 0
		},
		{
			"name": "drm",
			"display_name": "DRM",
			"num_errors": 2
		},
		{
			"name": "exiv2",
			"display_name": "EXIV2",
			"num_errors": 0
		}
	]
}
  • extractors[].name - (string) The actual name of the extractor that ran in this harvest. This value is used as {extractor} in all other Activity endpoint API requests.
  • extractors[].display_name - (string) The display name of the extractor that ran in this harvest
  • extractors[].num_error - (integer) Amount of errors the extractor caught

List Errors for an Extractor

This API will give you details on an error for a specific item_id, request_id and extractor.

GET /api/data/v3/activity/item/{item_id}/{request_id}/extractors/{extractor}
  • {item_id} - (string) The Item ID
  • {request_id} - (string) Harvest Job request ID
  • {extractor} - (string) Extractor name

You will receive the following response:

{
    "extractor": "audioinfo",
    "extractor_name": "Audio Info",
    "errors": [
        {
            "error": "audioinfo: no audio",
            "error_hash": "6199cf359b32392d186f07f7756e165c"
        }
    ]
}
  • extractor - (string) The actual name of the extractor being searched
  • extractor_name - (string) The display name of the extractor being searched
  • errors[].error - (string) The error message that occured
  • errors[].error_hash - (string) The MD5 hash of the error message

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.