---
title: "Submit a matrix to the asynchronous lane."
method: POST
path: "/v1/jobs/matrix"
tags: ["routing"]
---

# Submit a matrix to the asynchronous lane.

`POST /v1/jobs/matrix`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/v1/jobs/matrix`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

## Request body

- object

## Response `202`

Accepted and queued. Poll `result_url`, or wait for the signed webhook

- JobAcceptedResponse: The 202 answer to a submission.
  - `id` string, required: The job id to poll.
  - `kind` string, required: `optimise`, `replan` or `matrix`.
  - `result_url` string, required: Where to fetch it. The same URL the webhook will carry.
  - `status` string, required: Always `queued`, the worker has not looked at it yet.
  - `units_charged` integer, required: Quota units this submission drew. Charged now, refunded in full if the job fails.

## Other responses

- `400`: Invalid matrix request, or an unusable `webhook_url`
- `401`: Missing or invalid API key
- `409`: A `webhook_url` was given but the key has no webhook signing secret
- `422`: More than `SN_MATRIX_MAX_ELEMENTS_ASYNC` elements, or a matrix spanning further than the engine's `max_matrix_distance`
- `429`: Quota, rate limit, or too many jobs already queued or running

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)