diff --git a/snippets/whitelabel/ai/json.mdx b/snippets/whitelabel/ai/json.mdx index ea63adf..9090efe 100644 --- a/snippets/whitelabel/ai/json.mdx +++ b/snippets/whitelabel/ai/json.mdx @@ -7,7 +7,16 @@ "completion": "

ChatGPT said: ...", "sources": "
{ return ( This endpoint autoscales; if you receive a 503 response, maintain traffic and - expect errors to resolve within a couple minutes. + expect errors to resolve within a minute. ); }; diff --git a/snippets/whitelabel/search/callback.mdx b/snippets/whitelabel/search/callback.mdx new file mode 100644 index 0000000..1f494cf --- /dev/null +++ b/snippets/whitelabel/search/callback.mdx @@ -0,0 +1,8 @@ +### Push notification + +```shell +curl -H "Authorization: Bearer $MASSIVE_TOKEN" \ +'https://render.joinmassive.com/search'\ +'?terms=amazon+simple+queue+service'\ +'&callback=https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8' +``` diff --git a/snippets/whitelabel/search/url.mdx b/snippets/whitelabel/search/url.mdx new file mode 100644 index 0000000..5b23e48 --- /dev/null +++ b/snippets/whitelabel/search/url.mdx @@ -0,0 +1,7 @@ +### Alternative URL + +```shell +curl -H "Authorization: Bearer $MASSIVE_TOKEN" \ +'https://render.joinmassive.com/search'\ +'?url=https%3A%2F%2Fwww.google.com%2Fsearch%3Fq%3Dfoo%2Bbar%2Bbaz%26hl%3Dfr%26gl%3Dfr%26ie%3DUTF-8' +``` diff --git a/web-render/ai.mdx b/web-render/ai.mdx index a4038d6..940d96b 100644 --- a/web-render/ai.mdx +++ b/web-render/ai.mdx @@ -84,19 +84,20 @@ Completions are returned as structured JSON, rendered HTML, or raw (unrendered) If you set the output to JSON, your completion will be parsed into an object with the [geotargeting keys and values above](#service-usage) and following chat keys and values: -| Key | Value | -| :------------------- | :----------------------------------------------------------------------------------------------------------------------- | -| `model` | The AI model that generated the completion | -| `query` | The user prompt that the completion was generated for | -| `html` | The rendered HTML of the entire conversation | -| `prompt` | The rendered HTML of just the prompt portion of the conversation | -| `completion` | The rendered HTML of just the completion portion of the conversation | -| `sources` | The rendered HTML of just the sources portion of the conversation | -| `ads` | The rendered HTML of just the ads portion of the conversation | -| `fanouts` | An array of the fanout queries that the model searched to generate the completion; only some models expose these queries | -| `device` | The emulated device name that the conversation was had on | -| `language` (planned) | The common name or ISO code of the language that the conversation is in | -| `display` (planned) | The common name or ISO code of the display language that conversation interface is in | +| Key | Value | +| :----------------------- | :----------------------------------------------------------------------------------------------------------------------- | +| `model` | The AI model that generated the completion | +| `query` | The user prompt that the completion was generated for | +| `html` | The rendered HTML of the entire conversation | +| `prompt` | The rendered HTML of just the prompt portion of the conversation | +| `completion` | The rendered HTML of just the completion portion of the conversation | +| `sources` | The rendered HTML of just the sources portion, if any, of the conversation | +| `ads` | The rendered HTML of just the ads portion, if any, of the conversation | +| `sse` (ChatGPT only) | The server-sent events JSON that was used to populate the conversation HTML | +| `fanouts` (ChatGPT only) | An array of the fanout queries that the model searched to generate the completion; only some models expose these queries | +| `device` | The emulated device name that the conversation was had on | +| `language` (planned) | The common name or ISO code of the language that the conversation is in | +| `display` (planned) | The common name or ISO code of the display language that conversation interface is in | diff --git a/web-render/openapi.json b/web-render/openapi.json index da2b10c..57cf824 100644 --- a/web-render/openapi.json +++ b/web-render/openapi.json @@ -80,6 +80,16 @@ "schema": { "type": "string", "example": null }, "in": "query" }, + { + "name": "url", + "description": "The encoded URL of the results page to retrieve; if given, the URL overrides any of the above params.", + "schema": { + "type": "string", + "format": "uri", + "example": "https://www.google.com/search?q=foo+bar+baz&hl=fr&gl=fr&ie=UTF-8" + }, + "in": "query" + }, { "name": "awaiting", "description": "The lazy result features to wait to load; any AI overview, which can take significant time to generate, is awaited for a maximum of **1 minute**; multiple features can be provided by repeating the key; lazy results aren’t awaited by default.", @@ -97,6 +107,15 @@ "description": "The synchronous or asynchronous mode of results retrieval (see the [async resource](search/results)).", "schema": { "$ref": "#/components/schemas/Mode" }, "in": "query" + }, + { + "name": "callback", + "description": "The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the (prerequisite) asynchronous results have been retrieved.", + "schema": { + "type": "string", + "example": "https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8" + }, + "in": "query" } ], "responses": { @@ -393,7 +412,7 @@ "description": "The difficulty pool to attempt to access the URL from.", "schema": { "type": "string", - "enum": ["low", "medium", "high (planned)"], + "enum": ["low", "medium", "high"], "default": "low", "example": "low" }, @@ -613,7 +632,7 @@ "example": "user@example.com" }, "credits": { - "description": "The number of credits to grant the account.", + "description": "The number of API credits to preload the account with.", "type": "integer", "example": 1000 } @@ -633,7 +652,7 @@ "type": "object", "properties": { "email": { - "description": "The account email address as recorded by the API.", + "description": "The email address of the new account as recorded by the API.", "type": "string", "format": "email", "example": "user@example.com" @@ -642,9 +661,14 @@ "description": "The bearer token issued to the account for authentication.", "type": "string", "example": "a1-0dF6qKHYD7SNU5kAtjOmwHpH3iFgpylA" + }, + "credits": { + "description": "The number of initial credits granted to the account.", + "type": "integer", + "example": 1000 } }, - "required": ["email", "token"] + "required": ["email", "token", "credits"] } } } @@ -658,6 +682,54 @@ "500": { "$ref": "#/components/responses/unknownError" } } }, + "get": { + "summary": "Credit balances", + "description": "Retrieve the settings and credits of one or more accounts.", + "parameters": [ + { + "name": "email", + "description": "The (case-insensitive) email address of the user whose profile to fetch; multiple addresses can be provided by repeating the key; profiles for all addresses are fetched by default.", + "schema": { + "type": "array", + "items": { "type": "string", "format": "email", "example": "user@example.com" } + }, + "in": "query" + } + ], + "responses": { + "200": { + "description": "The account settings and credits.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "email": { + "description": "The account email address.", + "type": "string", + "format": "email", + "example": "user@example.com" + }, + "credits": { + "description": "The number of remaining API credits allocated to the account.", + "type": "integer", + "example": 1000 + } + }, + "required": ["email", "credits"] + } + } + } + } + }, + "401": { "$ref": "#/components/responses/authenticationError" }, + "403": { "$ref": "#/components/responses/authorizationError" }, + "429": { "$ref": "#/components/responses/throttlingError" }, + "500": { "$ref": "#/components/responses/unknownError" } + } + }, "patch": { "summary": "Credit grant", "description": "Allocate credits to an account.", @@ -668,13 +740,13 @@ "type": "object", "properties": { "email": { - "description": "The (case-insensitive) email address of the user whose account to grant credits to.", + "description": "The (case-insensitive) email address of the user whose account to grant credits.", "type": "string", "format": "email", "example": "user@example.com" }, "amount": { - "description": "The number of credits to grant the account.", + "description": "The number of additional API credits to grant the account.", "type": "integer", "example": 1000 } @@ -687,7 +759,7 @@ }, "responses": { "200": { - "description": "The account credits.", + "description": "The updated account credits.", "content": { "application/json": { "schema": { @@ -700,7 +772,7 @@ "example": "user@example.com" }, "credits": { - "description": "The number of granted credits as recorded by the API.", + "description": "The number of updated API credits allocated to the account.", "type": "integer", "example": 1000 } @@ -719,51 +791,59 @@ "500": { "$ref": "#/components/responses/unknownError" } } }, - "get": { - "summary": "Credit balances", - "description": "Retrieve the settings and remaining credits of one or more accounts.", - "parameters": [ - { - "name": "email", - "description": "The (case-insensitive) email address of the user whose profile to fetch; multiple addresses can be provided by repeating the key; profiles for all addresses are fetched by default.", - "schema": { - "type": "array", - "items": { "type": "string", "format": "email", "example": "user@example.com" } - }, - "in": "query" - } - ], + "delete": { + "summary": "User deactivation", + "description": "Disable an account.", + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "email": { + "description": "The (case-insensitive) email address of the user whose account to deactivate.", + "type": "string", + "format": "email", + "example": "user@example.com" + } + }, + "required": ["email"] + } + } + }, + "required": true + }, "responses": { "200": { - "description": "The account settings and credits.", + "description": "The confirmed account credits.", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "description": "The account email address.", - "type": "string", - "format": "email", - "example": "user@example.com" - }, - "credits": { - "description": "The number of remaining credits allocated to the account.", - "type": "integer", - "example": 1000 - } + "type": "object", + "properties": { + "email": { + "description": "The account email address.", + "type": "string", + "format": "email", + "example": "user@example.com" }, - "required": ["email", "credits"] - } + "credits": { + "description": "The zeroed-out credits as confirmed by the API.", + "type": "integer", + "example": 0 + } + }, + "required": ["email", "credits"] } } } }, "401": { "$ref": "#/components/responses/authenticationError" }, "403": { "$ref": "#/components/responses/authorizationError" }, + "400": { "$ref": "#/components/responses/malformedError" }, + "422": { "$ref": "#/components/responses/paramsError" }, "429": { "$ref": "#/components/responses/throttlingError" }, + "404": { "$ref": "#/components/responses/unsupportedError" }, "500": { "$ref": "#/components/responses/unknownError" } } } @@ -905,6 +985,12 @@ "minimum": 1, "example": 17208 }, + "credits": { + "description": "The number of credits consumed by the API calls.", + "type": "integer", + "minimum": 0, + "example": 17208 + }, "meanSecs": { "description": "The average number of elapsed seconds of the API calls.", "type": "number", @@ -912,7 +998,16 @@ "example": 6.78 } }, - "required": ["email", "from", "to", "service", "result", "calls", "meanSecs"] + "required": [ + "email", + "from", + "to", + "service", + "result", + "calls", + "credits", + "meanSecs" + ] } } } @@ -1196,7 +1291,12 @@ "type": "string", "example": "
Search | 1 | -| AI | 1 | +| AI | 5 | | Browser | 1 | | Reporting | 0 (free) | | Administration | 0 (free) | -A few premium parameters multiply the base cost of calls that use them: +CDP sessions are billed by time, rounded down to the nearest credit: -| Service | Key | Value | Credit multiplier | -| :------ | :----------- | :----------- | :---------------- | -| Browser | `difficulty` | `medium` | 2 | -| Browser | `speed` | `ridiculous` | 1.5 | +| Service | Base credits | +| :-------------------------------------- | :----------- | +| Browser CDP | 10 / minute | + +A few premium parameters multiply the base cost of calls or sessions that use them: + +| Service | Key | Value | Credit multiplier | +| :------------ | :----------- | :-------------------- | :---------------- | +| Browser (CDP) | `difficulty` | `medium` | 2 | +| Browser (CDP) | `difficulty` | `high` | 6 | +| Browser | `speed` | `ridiculous` | 2 | +| Browser | `speed` | `ludicrous` (planned) | 4 | For example, calling the browser service successfully with both `difficulty=medium` and -`speed=ridiculous` params would cost **3 credits** in total: +`speed=ridiculous` params would cost **4 credits** in total: -1 base credit x 2 x 1.5 = 3 total credits +1 base credit x 2 (difficulty multiplier) x 2 (speed multiplier) = 4 total credits Create or fund an account. diff --git a/web-render/search.mdx b/web-render/search.mdx index f975425..7599145 100644 --- a/web-render/search.mdx +++ b/web-render/search.mdx @@ -11,7 +11,9 @@ import { Autoscaling } from '/snippets/whitelabel/autoscaling.mdx'; import Authentication from '/snippets/whitelabel/authentication.mdx'; import Terms from '/snippets/whitelabel/search/terms.mdx'; import Offset from '/snippets/whitelabel/search/offset.mdx'; +import Url from '/snippets/whitelabel/search/url.mdx'; import Awaiting from '/snippets/whitelabel/search/awaiting.mdx'; +import Callback from '/snippets/whitelabel/search/callback.mdx'; @@ -49,8 +51,10 @@ The keys and values **{companyName}** supports are as follows: | `uule` | ⬜ | The [proprietary encoded string](https://moz.com/blog/geolocation-the-ultimate-tip-to-emulate-local-search) for emulating the location to search from; if possible, the actual location is searched from not emulated; location emulation is unused by default | | `language` | ⬜ | The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) 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 | | `display` | ⬜ | The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the search interface's display language (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the display language is unset by default or set to the language if given | +| `url` | ⬜ | The encoded URL of the results page to retrieve; if given, the URL overrides any of the above params | | `awaiting` | ⬜ | The lazy result features to wait to load, an `ai` overview, "People also ask" `answers`, or sponsored `ads`; any AI overview, which can take significant time to generate, is awaited for a maximum of **1 minute**; multiple features can be provided by repeating the key; lazy results aren't awaited by default | | `expiration` | ⬜ | The age in days of when to consider cached results expired, where `0` disables caching; `1` is the default number of days before expiration | +| `callback` | ⬜ | The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the (prerequisite) asynchronous results have been retrieved | ### Response format @@ -62,4 +66,8 @@ feature infinite scrolling, the HTML of each page will be separated from the nex + + + + diff --git a/web-render/usage.mdx b/web-render/usage.mdx index 1c7f0b8..c174d59 100644 --- a/web-render/usage.mdx +++ b/web-render/usage.mdx @@ -46,6 +46,7 @@ The API will return a JSON array: "service": "browser", "result": "success", "calls": 17208, + "credits": 17208, "meanSecs": 6.78 }, { "email": "user@example.com", @@ -54,6 +55,7 @@ The API will return a JSON array: "service": "browser", "result": "failure", "calls": 18, + "credits": 0, "meanSecs": 60.22 }] ``` @@ -90,5 +92,6 @@ These are the response keys and values: | `service` | The service included in the data, `search`, `ai`, or `browser` | | `result` | The type of result included in the data, `success` or `failure` | | `calls` | The number of API calls of the service and result type | +| `credits` | The number of credits consumed by the API calls | | `meanSecs` | The average number of elapsed seconds of the API calls |