Retrieve Task

Retrieve scraping task data and actual review content using foreign_key, api_key, publisher_key, and task_id.

Endpoint

POST https://data.reviewdata.ai/retrieve-task/

Description

This endpoint allows you to retrieve task data and review content for completed scraping tasks. All four parameters (foreign_key, api_key, publisher_key, and task_id) are required. The publisher_key should match the publisher name from the original request (e.g., 'maps.google.com', 'yelp.com').

For completed tasks: Returns actual review data from S3 files with pagination support, duplicate removal, and standardized formatting. Reviews are automatically sorted by date (newest first) and deduplicated based on review_id.

For incomplete tasks: Returns task status information without review data.

Try It Out

Test this endpoint directly in your browser:

Retrieve Task

POST

Test this endpoint directly in your browser. Enter your API key and modify the request body as needed.

Request Body

Schema

{
  "api_key": "string",
  "foreign_key": "string",
  "publisher_key": "string",
  "page": "integer",
  "page_size": "integer",
  "task_id": "string"
}

Required Fields

Field	Type	Required	Description
`api_key`	string	Yes	Your API key for authentication
`foreign_key`	string	Yes	Foreign key identifier used when creating the original scraping request
`publisher_key`	string	Yes	Publisher name (e.g., 'maps.google.com', 'yelp.com') to identify the specific publisher task
`task_id`	string	Yes	Unique task identifier for the specific scraping task

Optional Fields

Field	Type	Default	Description
`page`	integer	1	Page number for pagination (minimum: 1)
`page_size`	integer	50	Number of reviews per page (minimum: 1, maximum: 1000)

Example Requests

Basic Request

{
  "api_key": "YOUR_API_KEY_HERE",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6"
}

Request with Pagination

{
  "api_key": "YOUR_API_KEY_HERE",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "page": 2,
  "page_size": 25,
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6"
}

Large Dataset Request

{
  "api_key": "YOUR_API_KEY_HERE",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "page": 1,
  "page_size": 100,
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6"
}

Response

Completed Task with Reviews (200)

{
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "batch_id": "TEST_1751004113518_i6yxcl",
    "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "related_task_ids": [],
    "task_status": 200,
    "business": {
        "publisher": "maps.google.com",
        "profile_key": "https://www.google.com/maps/place/@40.7094789,-74.0126167,886m/data=!3m2!1e3!5s0x89c2592f4977ef97:0xf78d57398ac93494!4m7!3m6!1s0x89c25a177d4bf5db:0x84e51f23e8c0a75c!8m2!3d40.7094789!4d-74.0100364!10e1!16s%2Fg%2F1thtf190!5m1!1e1?entry=ttu&g_ep=EgoyMDI1MDY",
        "reviews_urls": [
            "https://prod-data-only-client.s3.amazonaws.com/Review_URLs/9f9d2b5a-085c-4df3-bcca-20928f086925/900e2ff4-2d25-4576-ab18-b9b8e73c0bd6_0.jl"
        ],
        "id": "restaurant_001",
        "name": "McDonald's",
        "tags": [
            "restaurant",
            "pizza",
            "italian",
            "casual"
        ],
        "phone": "+12123852066",
        "address": {
            "zip": "10038",
            "city": "New York",
            "state": "NY",
            "street": "160 Broadway",
            "country": "USA"
        },
        "description": "Classic, long-running fast-food chain known for its burgers & fries."
    },
    "reviews": [
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT25wVFEzWkxPR1ZJYkdWS04zWjNlWEo2ZW01UVZGRRAB",
            "author_name": "Regimorais Raab",
            "author_id": null,
            "rating": 5,
            "text": "Rapidez incrível",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT25wVFEzWkxPR1ZJYkdWS04zWjNlWEo2ZW01UVZGRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOnpTQ3ZLOGVIbGVKN3Z3eXJ6em5QVFE%7C0cLUo1-b2qC%7C?hl=en",
            "posted_at": 1750727938010,
            "review_hash": "f2601fda3fb2e249204ff97d9710acd7",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pFeFEzSXpjVW8zZUdkalFYQkRiR2hSV2xWdVIzYxAB",
            "author_name": "gloria schuweiler",
            "author_id": null,
            "rating": 3,
            "text": "Some  how they  been getting  my order wrong.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2pFeFEzSXpjVW8zZUdkalFYQkRiR2hSV2xWdVIzYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOjExQ3IzcUo3eGdjQXBDbGhRWlVuR3c%7C0cLP3KjBeBa%7C?hl=en",
            "posted_at": 1750704405791,
            "review_hash": "3de49930bb5221fce5bb352146649726",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2t0bVYyODNNRUo2VWxCMVVGcGhRVGxtYzBKNUxXYxAB",
            "author_name": "Zadran Akram khan",
            "author_id": null,
            "rating": 2,
            "text": "Happy Wellcomen New And Last Chef Akram Zadran",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2t0bVYyODNNRUo2VWxCMVVGcGhRVGxtYzBKNUxXYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOktmV283MEJ6UlB1UFphQTlmc0J5LWc%7C0cKzlVRIta5%7C?hl=en",
            "posted_at": 1750596704474,
            "review_hash": "c11d5ca37c28d429beb161013fdd2c3d",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE",
            "author_name": "Ivana Donev",
            "author_id": null,
            "rating": 4,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEKPshtbns_2pTw%7CCgwI8oq2wgYQsPr9wQE%7C?hl=en",
            "posted_at": 1749910898406,
            "review_hash": "d7f32bfcdd9e46b23f04b2d69e1fe373",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT214TVVHTjNWMkZzVjFSMlQzQmhSMVoyYWtKZmRuYxAB",
            "author_name": "Ludovic Pagès",
            "author_id": null,
            "rating": 2,
            "text": "C'est déjà le bas du panier en France, ben ce n'est pas mieux sur Broadway à Wall Street. Je ne comprends pas pour quoi ça existe encore. Pour le reste ce resto a un service rapide et des toilettes propres.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT214TVVHTjNWMkZzVjFSMlQzQmhSMVoyYWtKZmRuYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOmxMUGN3V2FsV1R2T3BhR1Z2akJfdnc%7C0cI7yCrlChX%7C?hl=en",
            "posted_at": 1749847949935,
            "review_hash": "56848456ebc3393b5aa98a3134242221",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT20xS1UyWjRNR2hLTUdRd2RERmlVVXd4VDFOblgyYxAB",
            "author_name": "Aaron Moore",
            "author_id": null,
            "rating": 5,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT20xS1UyWjRNR2hLTUdRd2RERmlVVXd4VDFOblgyYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOm1KU2Z4MGhKMGQwdDFiUUwxT1NnX2c%7C0cI4FOfmJHX%7C?hl=en",
            "posted_at": 1749832729734,
            "review_hash": "ce4e8f08dbe2fda5d996cf906b553450",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VQX3FpdmVkMHBhSlNREAE",
            "author_name": "Cevdet S A",
            "author_id": null,
            "rating": 5,
            "text": "Like it.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VQX3FpdmVkMHBhSlNREAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEP_qived0paJSQ%7CCgsI5p2pwgYQqMTXfA%7C?hl=en",
            "posted_at": 1749700326261,
            "review_hash": "433aa5e69074d92921cdac0b848ec3fd",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pZelVUQTVVRkp3YVhGa1lUTlBVVk42VWxGcE9GRRAB",
            "author_name": "Vinod Sukhadia",
            "author_id": null,
            "rating": 5,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2pZelVUQTVVRkp3YVhGa1lUTlBVVk42VWxGcE9GRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOjYzUTA5UFJwaXFkYTNPUVN6UlFpOFE%7C0cHNU251Vof%7C?hl=en",
            "posted_at": 1749649347101,
            "review_hash": "aa0b25c137f7b386a6d392f91b54b5e0",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VPM0E4N2k4a2V6SEJ3EAE",
            "author_name": "Husnain Ali",
            "author_id": null,
            "rating": 4,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VPM0E4N2k4a2V6SEJ3EAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEO3A87i8kezHBw%7CCgwI4c2jwgYQ2Mjj1wE%7C?hl=en",
            "posted_at": 1749608161452,
            "review_hash": "b7e33c65de9262919ad22741f0554832",
            "language": "en"
        },
        {
            "review_id": "ChdDSUhNMG9nS0VJQ0FnSURwX3QtdHJBRRAB",
            "author_name": "Fred Alluso",
            "author_id": null,
            "rating": 4,
            "text": "Clean, noisy, crowded. Most importantly they didn't mess up my coffee order.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChdDSUhNMG9nS0VJQ0FnSURwX3QtdHJBRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEICAgIDp_t-trAE%7C0cMTWPpdFWz%7C?hl=en",
            "posted_at": 1692756313115,
            "review_hash": "924067883b209b62d4ffd556179d9634",
            "language": "en"
        }
    ],
    "pagination": {
        "total_reviews": 11820,
        "page": 1,
        "page_size": 10,
        "total_pages": 1182,
        "has_next": true,
        "has_previous": false
    }
}

Task In Progress

{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "in_progress",
      "message": "Task is currently being processed",
      "task_status": 101
    }
  ]
}

Task Queued

{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "queued",
      "message": "Task is queued and waiting to be processed",
      "task_status": 100
    }
  ]
}

Task Failed

{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "failed",
      "message": "Task processing failed",
      "task_status": 500
    }
  ]
}

Response Fields

Task Information

Field	Type	Description
`foreign_key`	string	Your original foreign key identifier
`batch_id`	string	Batch identifier for grouping related tasks
`task_id`	string	Unique task identifier
`related_task_ids`	array	Array of related task identifiers
`task_status`	integer	HTTP status code indicating task completion status
`business`	object	Business information object (only for completed tasks)
`reviews`	array	Array of review objects (only for completed tasks)
`pagination`	object	Pagination information (only for completed tasks)

Business Object

Field	Type	Description
`id`	string	Business identifier
`name`	string	Business name
`tags`	array	Array of business category tags
`phone`	string	Business phone number
`address`	object	Business address information
`publisher`	string	Review publisher/platform (e.g., "maps.google.com")
`profile_key`	string	URL to the business profile on the review platform
`reviews_urls`	array	Array of URLs to raw review data files

Review Object

Field	Type	Description
`review_id`	string	Unique review identifier
`author_name`	string	Name of the reviewer
`author_id`	string	Unique identifier for the reviewer (nullable)
`rating`	integer	Review rating (1–5)
`text`	string	Review text content
`url`	string	URL to the original review
`posted_at`	integer	Unix timestamp when review was posted
`review_hash`	string	Unique hash for deduplication
`language`	string	Language code of the review

Pagination Object

Field	Type	Description
`total_reviews`	integer	Total number of reviews available
`page`	integer	Current page number
`page_size`	integer	Number of reviews per page
`total_pages`	integer	Total number of pages
`has_next`	boolean	Whether there are more pages
`has_previous`	boolean	Whether there are previous pages

Error Responses

Task Not Found (404)

{
  "error": "Task not found",
  "details": {
    "foreign_key": "The specified foreign key does not exist",
    "publisher_key": "The specified publisher key does not exist"
  }
}

Authentication Error (401)

{
  "error": "Invalid API key",
  "details": {
    "api_key": ["The provided API key is invalid"]
  }
}

Validation Error (400)

{
  "error": "Invalid request",
  "details": {
    "publisher_key": ["Publisher key is required"],
    "page": ["Page number must be at least 1"]
  }
}

Pagination

The API supports pagination for large datasets:

Default page size: 50 reviews per page
Maximum page size: 1000 reviews per page
Minimum page size: 1 review per page
Page numbering: Starts from 1

Pagination Example

// Get first page
const response1 = await fetch('/retrieve-task/', {
  method: 'POST',
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY_HERE',
    foreign_key: 'TEST_1751004113518_i6yxcl',
    publisher_key: 'maps.google.com',
    page: 1,
    page_size: 50,
    task_id: '900e2ff4-2d25-4576-ab18-b9b8e73c0bd6'
  })
});

// Get second page
const response2 = await fetch('/retrieve-task/', {
  method: 'POST',
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY_HERE',
    foreign_key: 'TEST_1751004113518_i6yxcl',
    publisher_key: 'maps.google.com',
    page: 2,
    page_size: 50,
    task_id: '900e2ff4-2d25-4576-ab18-b9b8e73c0bd6'
  })
});

Supported Review Sites

This endpoint supports all configured review sites including:

maps.google.com
yelp.com
tripadvisor.com
facebook.com
trustpilot.com
And 80+ more review sites

Best Practices

Polling: For incomplete tasks, implement polling with exponential backoff
Pagination: Use pagination for large datasets to avoid timeout issues
Error Handling: Always check task status codes and handle errors appropriately
Caching: Cache completed task results to avoid unnecessary API calls

Next Steps

Learn about Webhooks for real-time notifications
Explore Data Models for detailed schema information
Check Examples for more use cases

Endpoint​

Description​

Try It Out​

Retrieve Task

Request Body (JSON)

Request Body​

Schema​

Required Fields​

Optional Fields​

Example Requests​

Basic Request​

Request with Pagination​

Large Dataset Request​

Response​

Completed Task with Reviews (200)​

Task In Progress​

Task Queued​

Task Failed​

Response Fields​

Task Information​

Business Object​

Review Object​

Pagination Object​

Error Responses​

Task Not Found (404)​

Authentication Error (401)​

Validation Error (400)​

Pagination​

Pagination Example​

Supported Review Sites​

Best Practices​

Next Steps​

Endpoint

Description

Try It Out

Request Body

Schema

Required Fields

Optional Fields

Example Requests

Basic Request

Request with Pagination

Large Dataset Request

Response

Completed Task with Reviews (200)

Task In Progress

Task Queued

Task Failed

Response Fields

Task Information

Business Object

Review Object

Pagination Object

Error Responses

Task Not Found (404)

Authentication Error (401)

Validation Error (400)

Pagination

Pagination Example

Supported Review Sites

Best Practices

Next Steps