---
title: Get Period By Id
slug: suite-documentation/get-period-by-id
docTags: 
createdAt: 2026-08-26T09:30:53.630Z
---

## Endpoint Information

- **URL**: `{gateway-url}/plan-periods/period/{periodId}`
- **Method**: `GET`
- **Authentication**: Required (`Bearer Token`)
- **Company Header**: Required (`X-Company-Id`)

## Headers

| Header          | Type   | Required | Description                                                                  |
| --------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `Authorization` | String | Yes      | Bearer token used for authentication. Example: `Bearer <your_access_token>`. |
| `X-Company-Id`  | Long   | Yes      | The company ID used to scope the request.                                    |
| `Accept`        | String | No       | Recommended value: `application/json`.                                       |

## Path Parameters

| Parameter  | Type | Required | Description                                             |
| ---------- | ---- | -------- | ------------------------------------------------------- |
| `periodId` | Long | Yes      | The unique ID of the period. Must be a positive number. |

## Request Body

This endpoint does not require a request body.

## Response Body

```json
{
  "data": {
    "id": 628,
    "periodType": "MANUAL",
    "startDate": null,
    "endDate": null,
    "onceDate": null,
    "daysOfWeek": "2,3,4,5,6,7,1",
    "repeatPeriod": 60
  }
}
```

## Response Fields

| Parameter           | Type    | Description                                                                        |
| ------------------- | ------- | ---------------------------------------------------------------------------------- |
| `data`              | Object  | Period details.                                                                    |
| `data.id`           | Long    | Unique ID of the period.                                                           |
| `data.periodType`   | String  | Type of period. Possible values: `MANUAL`, `ONCE`, `REPETITIVE`.                   |
| `data.startDate`    | String  | Start date of the period in ISO offset date-time format. Can be `null`.            |
| `data.endDate`      | String  | End date of the period in ISO offset date-time format. Can be `null`.              |
| `data.onceDate`     | String  | Execution date for one-time periods in ISO offset date-time format. Can be `null`. |
| `data.daysOfWeek`   | String  | Comma-separated days of week used for repetitive periods. Can be `null`.           |
| `data.repeatPeriod` | Integer | Repeat interval value used for repetitive periods. Can be `null`.                  |

## Behavior Notes

- This endpoint retrieves a period by `periodId`, not by `planId`.
- If you only have `planId`, first retrieve the plan details and use the `periodId` value from the plan response.
- Period lookup is scoped by `X-Company-Id`.
- The response does not include `result.code` or `result.message`.

## Error Response Format

Error responses use the common problem detail format.

```json
{
  "instance": "/plan-periods/period/999999",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.testinium.com/exception",
  "timestamp": "2026-08-18T12:08:41.165927056Z",
  "errorType": "EXCEPTION",
  "errors": {
    "code": 10006,
    "message": "Test period not found!"
  }
}
```

## Error Codes

| HTTP Code | Error Message           | Description                                                                                  |
| --------- | ----------------------- | -------------------------------------------------------------------------------------------- |
| 400       | `BAD_REQUEST`           | The request is malformed, contains invalid path parameters, or a required header is missing. |
| 401       | `UNAUTHORIZED`          | Authentication failed, authentication is required, or the token is invalid.                  |
| 403       | `FORBIDDEN`             | The user does not have permission to access the requested company or resource.               |
| 404       | `NOT_FOUND`             | The requested period could not be found.                                                     |
| 405       | `METHOD_NOT_ALLOWED`    | The HTTP method is not supported. This endpoint only supports `GET`.                         |
| 503       | `SERVICE_UNAVAILABLE`   | The routed project service is unavailable.                                                   |
| 500       | `INTERNAL_SERVER_ERROR` | An unexpected error occurred on the server side.                                             |

## Application Error Codes

| Code    | Error Type   | HTTP Code | Description                                                                         |
| ------- | ------------ | --------- | ----------------------------------------------------------------------------------- |
| `10000` | `EXCEPTION`  | 401       | Authentication failed.                                                              |
| `10001` | `EXCEPTION`  | 401       | Authentication is required to access this resource.                                 |
| `10002` | `EXCEPTION`  | 401       | The provided token is invalid.                                                      |
| `10003` | `EXCEPTION`  | 403       | The user is not authorized for the requested resource.                              |
| `10004` | `EXCEPTION`  | 400       | A required header is missing. For example, `X-Company-Id` is not provided.          |
| `10005` | `EXCEPTION`  | 401       | A required token claim is missing.                                                  |
| `10006` | `EXCEPTION`  | 404       | The requested period could not be found.                                            |
| `10007` | `EXCEPTION`  | 403       | The user does not have access to the requested resource.                            |
| `10008` | `EXCEPTION`  | 503       | The routed project service is unavailable.                                          |
| `20005` | `VALIDATION` | 400       | The `periodId` path parameter is invalid. For example, it is not a positive number. |
| `20008` | `EXCEPTION`  | 400       | The `periodId` path parameter has an invalid type.                                  |
| `20009` | `EXCEPTION`  | 405       | The HTTP method is not supported.                                                   |

## Example Request

```bash
curl --location '{gateway-url}/plan-periods/period/{periodId}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'X-Company-Id: <company_id>'
```