Pocket API: Retrieving a User's Pocket Data
Pocket's /v3/get endpoint is a single call that is incredibly versatile. A few examples of the types of requests you can make:
- Retrieve a user’s list of unread items
- Sync data that has changed since the last time your app checked
- Retrieve paged results sorted by the most recent saves
- Retrieve just videos that the user has saved
- Search for a given keyword in item’s title and url
- Retrieve all items for a given domain
- and more
Required Permissions
In order to use the /v3/get endpoint, your consumer key must have the "Retrieve" permission.
Retrieving a User's Pocket Data
To retrieve item(s) from a user’s Pocket list, you’ll make a request to the /v3/get endpoint.
Method URL
https://getpocket.com/v3/get
Required Parameters
| consumer_key | string | Your application's Consumer Key | |
| access_token | string | The user's Pocket access token |
Optional Parameters
| state | string | See below for valid values | |
| favorite | 0 or 1 | See below for valid values | |
| tag | string | See below for valid values | |
| contentType | string | See below for valid values | |
| sort | string | See below for valid values | |
| detailType | string | See below for valid values | |
| search | string | Only return items whose title or url contain the search string | |
| domain | string | Only return items from a particular domain | |
| since | timestamp | Only return items modified since the given since unix timestamp | |
| count | integer | Only return count number of items. Note: There is a 30 item per request limit, any requests that go beyond this will be truncated to 30. | |
| offset | integer | Used only with count; start returning from offset position of results | |
| total | 0 or 1 | Use with offset and count to determine if there are more pages of results to retrieve. |
- unread = only return unread items
- archive = only return archived items
- all = return both unread and archived items (default)
- 0 = only return un-favorited items
- 1 = only return favorited items
- tag_name = only return items tagged with tag_name
- _untagged_ = only return untagged items
- article = only return articles
- video = only return videos or articles with embedded videos
- image = only return images
- newest = return items in order of newest to oldest
- oldest = return items in order of oldest to newest
- title = return items in order of title alphabetically
- site = return items in order of url alphabetically
- simple = return basic information about each item, including title, url, status, and more
- complete = return all data about each item, including tags, images, authors, videos, and more
Example request (JSON):
POST /v3/get HTTP/1.1
Host: getpocket.com
Content-Type: application/json
{"consumer_key":"1234-abcd1234abcd1234abcd1234",
"access_token":"5678defg-5678-defg-5678-defg56",
"count":"10",
"detailType":"complete"}Example response (JSON):
HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK
{"status":1,"list":{"229279689":{"item_id":"229279689",
"resolved_id":"229279689",
"given_url":"http:\/\/www.grantland.com\/blog\/the-triangle\/post\/_\/id\/38347\/ryder-cup-preview",
"given_title":"The Massive Ryder Cup Preview - The Triangle Blog - Grantland",
"favorite":"0",
"status":"0",
"resolved_title":"The Massive Ryder Cup Preview",
"resolved_url":"http:\/\/www.grantland.com\/blog\/the-triangle\/post\/_\/id\/38347\/ryder-cup-preview",
"excerpt":"The list of things I love about the Ryder Cup is so long that it could fill a (tedious) novel, and golf fans can probably guess most of them.",
"is_article":"1",
"has_video":"1",
"has_image":"1",
"word_count":"3197",
"images":{"1":{"item_id":"229279689","image_id":"1",
"src":"http:\/\/a.espncdn.com\/combiner\/i?img=\/photo\/2012\/0927\/grant_g_ryder_cr_640.jpg&w=640&h=360",
"width":"0","height":"0","credit":"Jamie Squire\/Getty Images","caption":""}},
"videos":{"1":{"item_id":"229279689","video_id":"1",
"src":"http:\/\/www.youtube.com\/v\/Er34PbFkVGk?version=3&hl=en_US&rel=0",
"width":"420","height":"315","type":"1","vid":"Er34PbFkVGk"}}}}}
The JSON response will include a list object. This object will contain all of the items that matched your retrieval request. Each item may or may not contain the following information:
- item_id - A unique identifier matching the saved item. This id must be used to perform any actions through the v3/modify endpoint.
- resolved_id - A unique identifier similar to the item_id but is unique to the actual url of the saved item. The resolved_id identifies unique urls. For example a direct link to a New York Times article and a link that redirects (ex a shortened bit.ly url) to the same article will share the same resolved_id. If this value is 0, it means that Pocket has not processed the item. Normally this happens within seconds but is possible you may request the item before it has been resolved.
- given_url - The actual url that was saved with the item. This url should be used if the user wants to view the item.
- resolved_url - The final url of the item. For example if the item was a shortened bit.ly link, this will be the actual article the url linked to.
- given_title - The title that was saved along with the item.
- resolved_title - The title that Pocket found for the item when it was parsed
- favorite - 0 or 1 - 1 If the item is favorited
- status - 0, 1, 2 - 1 if the item is archived - 2 if the item should be deleted
- excerpt - The first few lines of the item (articles only)
- is_article - 0 or 1 - 1 if the item is an article
- has_image - 0, 1, or 2 - 1 if the item has images in it - 2 if the item is an image
- has_video - 0, 1, or 2 - 1 if the item has videos in it - 2 if the item is a video
- word_count - How many words are in the article
- tags - A JSON object of the user tags associated with the item
- authors - A JSON object listing all of the authors associated with the item
- images - A JSON object listing all of the images associated with the item
- videos - A JSON object listing all of the videos associated with the item
Best Practices
- Retrieving User's List: After retrieving a User's list, you should store the current time (which is provided along with the list response) and pass that in the next request for the list using the 'since' parameter. This way the server will only return the changes that have ocurred since the last request.
Pagination
The maximum page size limit is 30 results. In order to retrieve more, you must paginate the result set. The count, offset, and total parameters are used for pagination. When the request is returned, if the value of total exceeds the value of count + offset, then there are still more pages of results to retrieve.
Example request - First Page (JSON):
POST /v3/get HTTP/1.1
Host: getpocket.com
Content-Type: application/json
{
"consumer_key":"1234-abcd1234abcd1234abcd1234",
"access_token":"5678defg-5678-defg-5678-defg56",
"count":"10",
"total": "1",
"detailType":"simple"
}Example response - More Results Available (JSON):
HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK
{"status":1,
"list": {...},
"total": 13
}
Example request - Next Page (JSON):
POST /v3/get HTTP/1.1
Host: getpocket.com
Content-Type: application/json
{
"consumer_key":"1234-abcd1234abcd1234abcd1234",
"access_token":"5678defg-5678-defg-5678-defg56",
"count":"10",
"offset": "10",
"total": "1",
"detailType":"simple"
}Example response - No More Results (JSON):
HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK
{"status":1,
"list": {...},
"total": 13
}
The value of count + offset is (10 + 10) = 20. The total value is 13, which is less than 20. Therefore all results have been received, so no more requests are necessary (incrementing offset and requesting more results will just return an empty set).
Error Handling
View the Error and Response Headers Documentation for detailed information on how to respond to errors.