Cloudinary SDK: Admin API
Use the Admin API to get information about resources based on tag applied. The API uses the GET method and supplies input using query string parameters.

List by Tag Function

Besides a number of helper functions like the URL Helper, the Cloudinary provides two Rest APIs: Admin API and Upload API. Both APIs are implemented as functions in many popular programming languages and frameworks like JavaScript, React, Angular, Vue.js, node.js, Python, Ruby, .net, and PHP.
We'll be using on the process that we've been using in the previous example:
  • code function
  • update template
  • package
  • build
  • test
  • deploy
For simplicity we'll continue to use the same template and just add a new function.
We'll use the GET method and async/await within the Lambda to call Cloudinary SDK functions.

Admin API

The Admin API provides administrative functionality to lend a hand in organizing the media repository that Cloudinary maintains for each user. In this section we'll use the Admin API to get a list of asset that contain a particular tag string. Tags can be added during content upload or in an update mode with the Admin API. Assets can have multiple tags. Tags become part of the set of meta data that is useful for organizing and filtering media.
We'll create a function that accepts uses two parameters: search_tag and max_results to look up assets that match search_tag to a tag in the asset. The function will receive these through a GET method and return the result from Cloudinary. The result contains an array of asset that contain the tag.

Code Function

Use the CommonJS require to load the cloudinary library. Since the function is added to the existing app.js, the library has already be npm installed and the library already in the code.
const cloudinary = require("cloudinary").v2;
The function uses await to guarantee result or error and a response is sent.
exports.listByTag = async (event) => {
The cloudinary.config() provides the 3 credentials needed by the Cloudinary SDK.
The input is provided to the function as Query String parameters and can be found in the event["queryStringParameters] object.
if (event["queryStringParameters"]['search_tag']) searchTag = event["queryStringParameters"]['search_tag'];
if (event["queryStringParameters"]['max_results']) maxResults = event["queryStringParameters"]['max_results'];
The Lambda function is defined using the async prefix, so that function calls returning promises within the lambda can use the await command.
exports.listByTag = async (event) => {
The call to the cloudinary.api.resources_by_tag function returns a promise. In order to deal with errors the call is wrapped in a try/catch block. If the call is successful the result returned by Cloudinary is forwarded to the caller.
exports.listByTag = async (event) => {
let response = {};
let searchTag = "";
let maxResults = "";
if (event["queryStringParameters"]['search_tag']) searchTag = event["queryStringParameters"]['search_tag'];
if (event["queryStringParameters"]['max_results']) maxResults = event["queryStringParameters"]['max_results'];
try {
const result = await cloudinary.api.resources_by_tag(searchTag, {
tags: true,
max_results: maxResults,
response.statusCode = 200;
response.headers = {"Content-Type": "application/json"};
response.body = JSON.stringify({ result: result });
} catch (error) {
response.statusCode = 500;
response.headers = {"Content-Type": "application/json"};
response.body = JSON.stringify({ error: error });
return response;


You can find out more about the SDK function that we'll be using, resources_by_tag, in the Cloudinary documentation. Many of the Cloudinary Node.js functions return promises. Recall that the functions we're creating for AWS Lambda are async. This works well with promises. It's imperative that we use the await command when we call the Cloudinary SDK functions that return promises.


This function needs the CLOUDINARY_URL, but that's already set up in the template. We'll add a new Resource entry and Output entries for the "ListByTagFunction".
Add the following Resource to the template.yaml. Notice that we've changed the Handler to call app.listByTag and the Path is /list-by-tag.
Type: AWS::Serverless::Function # More info about Function Resource:
CodeUri: hello-world/
Handler: app.listByTag
Runtime: nodejs12.x
Type: Api # More info about API Event Source:
Path: /list-by-tag
Method: get
Add the following Output configurations to the template.yaml. We add the output specifications for the Api, Function and Role.
Description: "API Gateway endpoint URL for Prod stage for list by tag function"
Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}"
Description: "List by tag Lambda Function ARN"
Value: !GetAtt ListByTagFunction.Arn
Description: "Implicit IAM Role created for list by tagfunction"
Value: !GetAtt ListByTagFunctionRole.Arn
The API includes the list-by-tag path.


With the function config added to the template we can create the package and assign AWS resources. The package command hasn't changed because we're using the same template. Execute the command in the root of the project.
sam package --template-file template.yaml --output-template-file package.yaml --s3-bucket my-bucket


The next step is to build the package. This adds the new function to the set of built files under the .aws directory. Since we're using the same template, we don't need to update the samconfig.toml file.
sam build


We can start a local web server using this command:
sam local start-api -n config.json
Using the web server we can test using cURL
curl --location \
--request GET ''
or postman.
Call /list-by-tag from Postman
If you want to use sam local invoke you must create an event.json file that mock what the event object must have for the function.
Create a file called events/list-by-tag.json under the root of the project.
"queryStringParameters": {
"search_tag": "sea-life",
"max_results": 10
The invoke the recent build using this command:
sam local invoke ListByTagFunction -n config.json -e events/list-by-tag.json


When tests are running successfully, you can deploy.
sam deploy
Testing the URL for /list-by-tag , the results show an array of assets that use the search_tag parameter supplies.
Copy link
On this page
List by Tag Function
Admin API
Code Function