List and filter files pinned to your Pinata account

Usage

import { PinataSDK } from "pinata-web3";

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT!,
  pinataGateway: "example-gateway.mypinata.cloud",
});

const files = await pinata.listFiles().name("pinnie")

Returns

type PinListItem = {
  id: string;
  ipfs_pin_hash: string;
  size: number;
  user_id: string;
  date_pinned: string;
  date_unpinned: string | null;
  metadata: {
    name: string | null;
    keyvalues: {
      [key: string]: any;
    } | null;
  };
  regions: {
    regionId: string;
    currentReplicationCount: number;
    desiredReplicationCount: number;
  }[];
  mime_type: string;
  number_of_files: number;
};

Parameters

Filter response with the following additional methods. All filters are optional.

name

  • Type: string

Name of the file

const files = await pinata
  .listFiles()
  .name('pinnie')

cid

  • Type: string

CID of the file

const files = await pinata
  .listFiles()
  .cid('rbafkreih5aznjvttude6c3wbvqeebb6rlx5wkbzyppv7garjiubll2ceym4r')

group

  • Type: string

Filter by groupId

const files = await pinata
  .listFiles()
  .group('648767d5-0a80-4b3a-9669-93693e4a0519')

keyValue

  • Type: object

Filter files by keyValue objects used in Pinata Metadata

const files = await pinata
  .listFiles()
  .keyValues("whimsey", 100)

This also includes an optional operator for even more fine tuned data

Type:

operator?:
		| "gt" // Greater than
		| "gte" // Greater or equal to
		| "lt" // Less than
		| "lte" // Less than or equal to
		| "ne" // Not equal
		| "eq" // Equal
		| "between"
		| "notBetween"
		| "like"
		| "notLike"
		| "iLike"
		| "notILike"
		| "regexp"
		| "iRegexp";
const files = await pinata
  .listFiles()
  .keyValues("whimsey", 400, "lt")

pageLimit

  • Type: number

Determine the number of results, default is 10, max is 1000

const files = await pinata
  .listFiles()
  .pageLimit(100)

pageOffset

  • Type: number

Offset the number of files returned to paginate

const files = await pinata
  .listFiles()
  .pageOffset(100)

pinStart

  • Type: string

Filter by start date in ISO8601 format

const files = await pinata
  .listFiles()
  .pinStart('2024-07-16T11:41:19Z')

pinEnd

  • Type: string

Filter by end date in ISO8601 format

const files = await pinata
  .listFiles()
  .pinEnd('2024-07-16T11:41:19Z')

pinSizeMin

  • Type: number

Filter by minimum file size in bytes

const files = await pinata
  .listFiles()
  .pinSizeMin('100000')

pinSizeMax

  • Type: number

Filter by maximum file size in bytes

const files = await pinata
  .listFiles()
  .pinSizeMax('1000000')

Auto Paginate

The listFiles method has an auto pagination feature that is triggered when used inside a for await iterator

for await (const item of pinata.listFiles().name("pinnie") {
  console.log(item.ipfs_pin_hash);
}

Works like magic ✨