You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
paramName
( optional Type array of paramType )
Undocumented.
Description of this parameter from the json schema.

Google Chrome Extensions (Labs)

chrome.history

Use the chrome.history module to interact with the browser's record of visited pages. You can add, remove, and query for URLs in the browser's history. To override the history page with your own version, see Override Pages.

Manifest

You must declare the "history" permission in the extension manifest to use the history API. For example:

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

Transition types

The history API uses a transition type to describe how the browser navigated to a particular URL on a particular visit. For example, if a user visits a page by clicking a link on another page, the transition type is "link".

The following table describes each transition type.

Transition type Description
"typed" The user got this page by typing the URL in the address bar. Also used for other explicit navigation actions. See also generated, which is used for cases where the user selected a choice that didn't look at all like a URL.
"auto_bookmark" The user got to this page through a suggestion in the UI — for example, through a menu item.
"auto_subframe" Subframe navigation. This is any content that is automatically loaded in a non-top-level frame. For example, if a page consists of several frames containing ads, those ad URLs have this transition type. The user may not even realize the content in these pages is a separate frame, and so may not care about the URL (see also manual_subframe).
"manual_subframe" For subframe navigations that are explicitly requested by the user and generate new navigation entries in the back/forward list. An explicitly requested frame is probably more important than an automatically loaded frame because the user probably cares about the fact that the requested frame was loaded.
"generated" The user got to this page by typing in the address bar and selecting an entry that did not look like a URL. For example, a match might have the URL of a Google search result page, but it might appear to the user as "Search Google for ...". These are not quite the same as typed navigations because the user didn't type or see the destination URL. See also keyword.
"start_page" The page was specified in the command line or is the start page.
"form_submit" The user filled out values in a form and submitted it. Note that in some situations — such as when a form uses script to submit contents — submitting a form does not result in this transition type.
"reload" The user reloaded the page, either by clicking the reload button or by pressing Enter in the address bar. Session restore and Reopen closed tab use this transition type, too.
"keyword" The URL was generated from a replaceable keyword other than the default search provider. See also keyword_generated.
"keyword_generated" Corresponds to a visit generated for a keyword. See also keyword.

Examples

For examples of using this API, see the history sample directory and the history API test directory. For other examples and for help in viewing the source code, see Samples.

API reference: chrome.history

Methods

addUrl

void chrome.history.addUrl(, object details)

Adds a URL to the history at the current time with a transition type of "link".

Parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
url
( Type array of string )
The URL to add.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(Type param1, Type param2) {...});

deleteAll

void chrome.history.deleteAll(, function callback)

Deletes all items from the history.

Parameters

callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...});

deleteRange

void chrome.history.deleteRange(, object range, function callback)

Removes all items within the specified date range from the history. Pages will not be removed from the history unless all visits fall within the range.

Parameters

range
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
startTime
( Type array of number )
Items added to history after this date, represented in milliseconds since the epoch.
endTime
( Type array of number )
Items added to history before this date, represented in milliseconds since the epoch.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function() {...});

deleteUrl

void chrome.history.deleteUrl(, object details)

Removes all occurrences of the given URL from the history.

Parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
url
( Type array of string )
The URL to remove.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(Type param1, Type param2) {...});

getVisits

void chrome.history.getVisits(, object details, function callback)

Retrieve information about visits to a URL.

Parameters

details
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
url
( Type array of string )
The URL for which to retrieve visit information. It must be in the format as returned from a call to history.search.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of VisitItem results) {...});
results
( Type array of VisitItem array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

search

void chrome.history.search(, object query, function callback)

Search the history for the last visit time of each page matching the query.

Parameters

query
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
text
( Type array of string )
A free-text query to the history service. Leave empty to retrieve all pages.
startTime
( optional Type array of number )
Limit results to those visited after this date, represented in milliseconds since the epoch.
endTime
( optional Type array of number )
Limit results to those visited before this date, represented in milliseconds since the epoch.
maxResults
( optional Type array of integer )
The maximum number of results to retrieve. Defaults to 100.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this: 

function(array of HistoryItem results) {...});
results
( Type array of HistoryItem array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

Events

onVisitRemoved

chrome.history.onVisitRemoved.addListener(function(object removed) {...});

Fired when one or more URLs are removed from the history service. When all visits have been removed the URL is purged from history.

Parameters

removed
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
allHistory
( Type array of boolean )
True if all history was removed. If true, then urls will be empty.
urls
( optional Type array of Type array of string paramType )
Undocumented.
Description of this parameter from the json schema.

onVisited

chrome.history.onVisited.addListener(function(HistoryItem result) {...});

Fired when a URL is visited, providing the HistoryItem data for that URL.

Parameters

result
( HistoryItem array of paramType )
Undocumented.
Description of this parameter from the json schema.

Types

VisitItem

paramName
( Type array of object )
An object encapsulating one visit to a URL.
id
( Type array of string )
The unique identifier for the item.
visitId
( Type array of string )
The unique identifier for this visit.
visitTime
( optional Type array of number )
When this visit occurred, represented in milliseconds since the epoch.
referringVisitId
( Type array of string )
The visit_id of the referrer.
transition
( Type array of string )
The transition type for this visit from its referrer.

HistoryItem

paramName
( Type array of object )
An object encapsulating one result of a history query.
id
( Type array of string )
The unique identifier for the item.
url
( optional Type array of string )
The URL navigated to by a user.
title
( optional Type array of string )
The title of the history page.
lastVisitTime
( optional Type array of number )
When this page was last loaded, represented in milliseconds since the epoch.
visitCount
( optional Type array of integer )
The number of times the user has navigated to this page.
typedCount
( optional Type array of integer )
The number of times the user has navigated to this page by typing in the address.