Pocket API: Retrieving a User's Pocket Data

Last Updated: November 7, 2012

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
offset integer Used only with count; start returning from offset position of results
state
  • unread = only return unread items (default)
  • archive = only return archived items
  • all = return both unread and archived items
favorite
  • 0 = only return un-favorited items
  • 1 = only return favorited items
tag
  • tag_name = only return items tagged with tag_name
  • _untagged_ = only return untagged items
contentType
  • article = only return articles
  • video = only return videos or articles with embedded videos
  • image = only return images
sort
  • 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
detailType
  • simple = only return the titles and urls of each item
  • 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

{"consumer_key":"1234-abcd1234abcd1234abcd1234",
"access_token":"5678defg-5678-defg-5678-defg56",
"since":"1348852386"}
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 Full List: Whenever possible, you should use the since parameter, or count and and offset parameters when retrieving a user's list. After retrieving the 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. This way the server only needs to return a small set (changes since that time) instead of the user's entire list every time.

Error Handling

View the Error and Response Headers Documentation for detailed information on how to respond to errors.