---
title: "Poll targeting job status"
method: GET
path: "/v1/data/targeting/meta/jobs/{job_id}"
tags: ["Targeting"]
---

# Poll targeting job status

`GET /v1/data/targeting/meta/jobs/{job_id}`

## Request

- Base URL: `https://api.mapulus.com`
- URL: `https://api.mapulus.com/v1/data/targeting/meta/jobs/{job_id}`
- Auth: HTTP bearer

Poll the status of a targeting job.

Returns the job status, and the result when completed.
Jobs are account-scoped — you can only access jobs created by your account.

## Path parameters

- `job_id` string, required

## Response `200`

Current status and result of a targeting job.

- ResponseEnvelopeTargetingJobStatus
  - `data` TargetingJobStatus, required: Response when polling a targeting job.
    - `job_id` string, required: UUID of the job.
    - `status` string, required: Job status (queued, processing, completed, failed).
    - `result` MetaTargetingResult: Result of Meta Ads targeting circle generation.
      - `mode` string: Targeting mode: 'circles' or 'postal'.
      - `inclusion` MetaCircle[], required: Inclusion (positive) circles.
        - `latitude` number, required: Circle centre latitude.
        - `longitude` number, required: Circle centre longitude.
        - `radius` number, required: Circle radius.
        - `distance_unit` string, required: Radius unit (kilometer or mile).
        - `address` string, nullable: Reverse-geocoded address of circle center.
      - `exclusion` MetaCircle[], required: Exclusion (negative) circles.
        - `latitude` number, required: Circle centre latitude.
        - `longitude` number, required: Circle centre longitude.
        - `radius` number, required: Circle radius.
        - `distance_unit` string, required: Radius unit (kilometer or mile).
        - `address` string, nullable: Reverse-geocoded address of circle center.
      - `postal_targets` MetaPostalTarget[], nullable: Postal inclusion targets (only in postal mode).
        - `key` string, required: Meta Ads key (e.g. 'US:90210' or '2000').
        - `code` string, required: Postal code (e.g. '90210').
        - `name` string, required: Postal area name.
        - `boundary_id` string, required: Mapulus boundary_id (e.g. 'us_zcta:90210').
      - `total_circles` integer, required: Total number of circles (inclusion + exclusion).
      - `inclusion_count` integer, required: Number of inclusion circles.
      - `exclusion_count` integer, required: Number of exclusion circles.
      - `postal_count` integer: Number of postal inclusion targets.
      - `radius_km` number, required: Maximum circle radius used (in km, regardless of output unit).
      - `radius_min_km` number, required: Minimum circle radius used (in km).
      - `boundary_ids` string[], required: Input boundary IDs.
      - `area_km2` number, required: Total area of unioned boundaries in km².
      - `concavity_ratio` number, required: Shape complexity (1.0 = convex, lower = more complex).
    - `error` string, nullable: Error message when failed.
    - `created_at` string, date-time, required: When the job was created.
    - `started_at` string, date-time, nullable: When processing started.
    - `completed_at` string, date-time, nullable: When the job completed.
  - `meta` ResponseMeta: Response metadata.
    - `request_id` string, nullable
    - `pagination` PaginationMeta: Pagination metadata for list responses.
      - `total` integer, required: Total number of matching records.
      - `limit` integer, required: Maximum records returned per page.
      - `offset` integer, required: Number of records skipped.
      - `has_more` boolean, required: Whether more records exist beyond this page.
    - `demographics` DemographicsMeta: Demographics-specific metadata returned with census data endpoints.
      - `topics_included` string[], required: Topics included in the response.
      - `topics_available` string[]: Additional topics available but not requested.
    - `sources` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mapulus/apis/mapulus-api.md) · [All operations](https://skmtc.dev/mapulus/apis/mapulus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mapulus/apis/mapulus-api/revisions/b99766fa053f?raw)