Annotation Tools Job Report

This article applies to using annotation tools, regardless of whether SDA has been set up for your team or not. 

Output Columns 

The output column in annotation tool contains json objects containing the URLs as well as a few metadata fields which are tool specific. Below is an example of the updated output:

type: "shapes",
metadata: { number_of_shapes: 4 },
url: "",
urlExpiresAt: "2023-04-24T19:40:08Z",

As mentioned above, the json output can also contain a number of metadata objects depending on which annotation tool(s) you are using. The above example is a Shapes tool output that contains the metadata object with the key number_of_shapes which corresponds to the total number of shape objects annotated with the tool for that row.

The updated json output now includes the urlExpiresAt key. The job result links will expire 15 days after generation; to receive non-expired result links, please re-generate the result report and download the job report again. You can use the developer docs to regenerate the report and download the report. Alternatively you can use the UI to regenerate and download the report as shown below.


Authentication to Access URLs

URLs in the report require authentication. 

See example below if you have scripts that operate on the output URLs: 

To call - replace your requestor-proxy hostname to api-gateway:

Once that is complete, add the api key at the end:


Using ref-to-url to translate CDS refs into URLs 

If units are stored in CDS but job design requires a URL, you can use a liquid filter to translate the CDS reference into a URL. The structure {{ data_column | ref_to_url }} will turn a CDS ref from data_column into a short-lived S3 link. In addition, you can use the /link endpoint in CDS to generate short-lived S3 links. 


Unit data 

"Hey Siri, what time is it?", ""{ "type":"file_upload",

CML code 

<audio src="{{ audio_file | ref_to_url }}" /> 

HTML on the assignment page 

<audio src="
jobs/123456/annotations/00112233-4455-6677-8899-aabbccddeeff00.wav?sig=xyz" />

Regenerating Expired Result Links

As mentioned above, job result urls for Annotation Tools expire 15 days after generation. Below is an alternative way to regenerate the expired links.

  1. Retrieve the valueRef from the expired JSON result and the team ID of the job the results came from. You can get your team ID by clicking “Team Jobs” in your account and copying the id in the URL after

  2. Retrieve your account api key

  3. Use 3600 for expiration_ms as this is how long the new token is valid for

  4. Create the following link:


    2. team_id+

    3. "&path="+

    4. value_ref+

    5. "&expires_in="+

    6. expiration_ms +

    7. "&key=" + api_key

    8. This is the new link

  5. Ping this new link to get a new Token

  6. new_link = "" + new_token


def regenerate_url(expired_result, team_id, expiration_ms=3600”):

link = expired_result['url']

value_ref = expired_result['valueRef']

end_value = team_id+"&path="+value_ref+ "&expires_in="+expiration_ms

anno = ""+end_value

anno = anno + "&key=" + api_key

response = requests.get(anno)

new_token = response.text

new_link = "" + new_token


Alternative with curl:

curl -H "Authorization: Token token=MYTOKEN" “{valuerRef}&expires_in=3600”



Then you can pass that output to redeem_token endpoint to get the file:

curl -H "Authorization: Token token=MYTOKEN" “”


Benefits of using CDS (Customer Data Service):

  • Better Integration: CDS URLs' are designed to work with all annotation tools output data, which could make it easier for any tools to integrate data with each other.

  • Secured: CDS URL’s are built with expiration time, this makes it very secure for clients.

  • Flexible: Using a CDS URL is a flexible alternative to store annotation as sizable and secure annotation data. Not only JSON data, but any sort of data, could be defined by a CDS URL.

  • Access control: Data in CDS has 1:1 relationship with Team ID. Only jobs under a permissible Team ID are authorized to access data in CDS using a short-lived link.

  • No Limit: The size of annotation data has no restrictions.

Was this article helpful?
16 out of 18 found this helpful

Have more questions? Submit a request
Powered by Zendesk