Pinata Docs
Search…
Pin Jobs

Endpoint

Description

Retrieves a list of all the pins that are currently in the pin queue for your user.

Type

GET

Headers

pinata_api_key: (put your personal pinata api key here)
pinata_secret_api_key: (put your personal pinata secret api key here)

OR

Authorization: Bearer (put your pinata JWT here)

Request Query

You have the option to filter the request with the following query parameters
Query parameters can be added onto the end of the pinJobs request URL using the following format:
https://api.pinata.cloud/pinning/pinJobs?filter=value&additionalFilter=value

Available filters:

  • "sort" - Sort the results by the date added to the pinning queue (see value options below)
    • "ASC" - Sort by ascending dates
    • "DESC" - Sort by descending dates
  • "status" - Filter by the status of the job in the pinning queue (see potential statuses below)
    • "prechecking" - Pinata is running preliminary validations on your pin request.
    • "searching" - Pinata is actively searching for your content on the IPFS network. This may take some time if your content is isolated.
    • "retrieving" - Pinata has located your content and is now in the process of retrieving it.
    • "expired" - Pinata wasn't able to find your content after a day of searching the IPFS network. Please make sure your content is hosted on the IPFS network before trying to pin again.
    • "over_free_limit" - Pinning this object would put you over the free tier limit. Please add a credit card to continue pinning content.
    • "over_max_size" - This object is too large of an item to pin. If you're seeing this, please contact us for a more custom solution.
    • "invalid_object" - The object you're attempting to pin isn't readable by IPFS nodes. Please contact us if you receive this, as we'd like to better understand what you're attempting to pin.
    • "bad_host_node" - You provided a host node that was either invalid or unreachable. Please make sure all provided host nodes are online and reachable.
  • "ipfs_pin_hash" - Retrieve the record for a specific IPFS hash
  • "limit" - Limit the amount of results returned per page of results (default is 5, and max is 1000)
  • "offset" - Provide the record offset for records being returned. This is how you retrieve records on additional pages (default is 0)

Response

The response for this call takes the form of a JSON object seen below. Each item in the "rows" array represents a pin job record that matched the query parameters you passed in.
1
{
2
count: (this is the total number of pin job records that exist for the query filters you passed in),
3
rows: [
4
{
5
id: (the id for the pin job record),
6
ipfs_pin_hash: (the IPFS multi-hash for the content you pinned),
7
date_queued: (The date this hash was initially queued to be pinned - represented in ISO 8601 format),
8
status: (The current status for the pin job),
9
name: (If you passed in a name for your hash, it will be listed here),
10
keyvalues: (If you passed in keyvalues for your hash, they will be listed here),
11
host_nodes: (If you provided host nodes for your hash, they will be listed here),
12
pin_policy: Once this content has been found, this is the pin policy that will be used for replications
13
},
14
{
15
same record format as above
16
}
17
.
18
.
19
.
20
]
21
}
Copied!

Postman Example

The Postman example shows a request that will return all records (with no filters)

JavaScript With Axios Example

In the javascript example below, we pass in our API keys from elsewhere (hopefully in a secure way).
We also pass in the query parameters that we wish to filter on.
1
const axios = require('axios');
2
3
export const pinJobs = (pinataApiKey, pinataSecretApiKey, queryParams) => {
4
const url = `https://api.pinata.cloud/pinning/pinJobs?status=searching&sort=DESC`;
5
return axios
6
.get(url, {
7
headers: {
8
pinata_api_key: pinataApiKey,
9
pinata_secret_api_key: pinataSecretApiKey
10
}
11
})
12
.then(function (response) {
13
//handle response here
14
})
15
.catch(function (error) {
16
//handle error here
17
});
18
};
Copied!

We want your feedback!

Have a suggestion? Have a complaint? Confused about something in the documentation? Just want to say hi?
We want to make Pinata the best product available. That involves listening to our users and addressing their needs.
Send us an email at [email protected] and we'll see how we can help.
Last modified 3mo ago