Retrieving Map Jobs

After creating a mapping job, you can retrieve it later instead of creating a new request.

The Map API provides two endpoints for this:

GET /v1/map/jobs — List your previous mapping jobs.
GET /v1/map/{job_id} — Retrieve the complete details of a specific mapping job.

These endpoints are useful for reviewing previous jobs, recovering after an application restart, and accessing discovered URLs.

Retrieval Workflow

The following diagram shows how both endpoints work together.

When to Use Each Endpoint

Endpoint	Use Case
`GET /v1/map/jobs`	View all of your previous mapping jobs.
`GET /v1/map/{job_id}`	Retrieve the complete details of one mapping job.

List Previous Mapping Jobs

Retrieve a paginated list of your mapping jobs.

GET /v1/map/jobs

A successful response contains a list of jobs together with pagination information.

Each job includes:

Field	Description
`job_id`	Unique identifier of the mapping job.
`url`	Website that was mapped.
`status`	Current job status.
`links_count`	Number of discovered URLs.
`duration_ms`	Time required to complete the job.
`search`	Search filter used when the job was created, if any.
`error_code`	Error code if the job failed. Otherwise `null`.
`created_at`	Time when the job started.
`completed_at`	Time when the job finished.

The response also includes:

Field	Description
`page`	Current page number.
`page_size`	Number of jobs returned per page.
`page_count`	Total number of available pages.

Finding the Right Job

Most applications identify a job by checking:

The website URL.
The job status.
The creation time.
The optional search filter.

Retrieve a Specific Mapping Job

Once you have a job_id, retrieve the complete job information.

GET /v1/map/{job_id}

This endpoint returns:

Job information.
Mapping configuration.
Statistics.
Every discovered URL.

Understanding the Response

A completed mapping job contains several sections.

Job Information

These fields describe the mapping job itself.

Field	Description
`job_id`	Unique job identifier.
`url`	Website that was mapped.
`status`	Current status of the mapping job.
`created_at`	Time when the job was created.
`completed_at`	Time when the job completed.

Mapping Configuration

These values show how the mapping job was executed.

Field	Description
`search`	Search filter applied during URL discovery.
`include_subdomains`	Indicates whether subdomains were included.
`ignore_query_parameters`	Indicates whether query parameters were ignored when discovering URLs.

Statistics

The response also includes useful information about the completed job.

Field	Description
`links_count`	Total number of discovered URLs.
`duration_ms`	Time taken to complete the mapping job.
`tokens_charged`	Number of API tokens charged for the request.

Discovered Links

The links array contains every URL discovered during the mapping process.

Each entry contains:

Field	Description
`url`	The discovered page URL.
`source`	Where the URL was discovered (`html` or `sitemap`).

Example:

{
  "url": "https://docs.geonode.com",
  "source": "sitemap"
}

Recovering Previous Jobs

If your application loses the original job_id, you don't need to create another mapping request.

Instead:

Call GET /v1/map/jobs.
Find the required job.
Copy its job_id.
Retrieve the complete results with GET /v1/map/{job_id}.

This approach helps avoid creating duplicate mapping jobs.

Best Practices

Save the returned job_id whenever you create a mapping job.
Use GET /v1/map/jobs to locate previous jobs if the identifier is unavailable.
Check the job status before using its results.
Review links_count to understand how many URLs were discovered.
Reuse completed mapping jobs whenever possible instead of creating duplicate requests.

Next Steps

Now that you know how to retrieve previous mapping jobs and inspect their results, continue to Best Practices to learn recommendations for building efficient and reliable mapping workflows.

Retrieving Map Jobs

On this page