Skip to main content
GET
/
search
Results
curl --request GET \
  --url https://api.agentfirst.dev/search \
  --header 'Authorization: Bearer <token>'
{
  "terms": "foo",
  "results": [
    {
      "type": "organic",
      "page": 1,
      "section": "main",
      "feature": 1,
      "position": 1,
      "url": "https://foofighters.com/",
      "title": "Foo Fighters",
      "site": "Foo Fighters",
      "visibleUrl": "https://foofighters.com",
      "date": null,
      "snippet": "Official website of Foo Fighters.",
      "rating": null,
      "votes": null,
      "sitelinks": [
        {
          "position": 1,
          "url": "https://foofighters.com/tour-dates/",
          "title": "Tour Dates"
        }
      ],
      "images": [
        {
          "position": 1,
          "source": "[Image data]",
          "altText": "foo from en.wikipedia.org"
        }
      ]
    }
  ],
  "resultsCount": 43,
  "pageCount": 1,
  "country": null,
  "subdivision": null,
  "city": null,
  "approxResultsCount": 255000000,
  "resultsOffset": null,
  "pageSize": null,
  "uule": null,
  "language": null
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
terms
string
required

The broad or exact word or phrase to query (e.g., foo bar baz or "foo bar baz"); the terms require form or URL encoding (with any space character being replaced by a + character or %20 sequence).

​
serps
integer
default:1

The number of results pages to retrieve.

Required range: 1 <= x <= 10
​
size
integer

The number of results per page to retrieve; page size is unset by default.

Required range: 0 <= x <= 100
​
offset
integer

The number of initial results to skip; results aren’t offset by default.

Required range: 0 <= x <= 100
​
country
string

The two-letter ISO code of the country to search from (these codes are case insensitive); a random country will be used by default.

​
subdivision
string

The alphanumeric second part (proceeding the separator) of a first-level subdivision code in the (prerequisite) country to search from (these codes are case insensitive); a random subdivision will be used by default.

​
city
string

The commonly spelled name of the city in the (prerequisite) country to search from (these names are temporarily case sensitive and required to include form- or URL-encoded spaces and punctuation marks); a random city will be used by default.

​
uule
string

The proprietary encoded string for emulating the location to search from; if possible, the actual location will be searched from not emulated; location emulation is unused by default.

​
language
string

The commonly spelled name, two-letter ISO code, or Google code of the language to search in (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the language is unset by default.

​
mode
enum<string>
default:sync

The synchronous or asynchronous timing of when to retrieve results (see the async endpoint).

Available options:
sync,
async
​
format
enum<string>
default:html

The format to output to.

Available options:
html,
json
​
subaccount
string

Any unique identifier of up to 255 characters (regardless of character encoding); we’ll bill requests made from subaccounts separately.

Response

The search results or a job identifier.

​
terms
string
required

The queried word or phrase.

Example:

"foo"

​
results
object[]
required
​
resultsCount
integer
required

The number of parsed results.

Required range: x >= 0
Example:

43

​
pageCount
integer
required

The number of retrieved results pages.

Required range: 1 <= x <= 10
Example:

1

​
country
string | null
required

The ISO code of the requested country.

Example:

null

​
subdivision
string | null
required

The partial ISO code of the requested subdivision.

Example:

null

​
city
string | null
required

The name of the requested city.

Example:

null

​
approxResultsCount
integer

The approximate number of indexed results.

Required range: x >= 0
Example:

255000000

​
resultsOffset
integer | null

The number of skipped initial results.

Required range: 0 <= x <= 100
Example:

null

​
pageSize
integer | null

The number of retrieved results per page.

Required range: 0 <= x <= 100
Example:

null

​
uule
string | null

The encoded string of the emulated location.

Example:

null

​
language
string | null

The name, ISO code, or Google code of the requested language.

Example:

null